First

.dockerignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+
+# Git
+.git/
+.gitignore
+
+# Environment files
+.env
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Documentation and notes
+*.md
+!README.md
+
+# Images and media (optional - remove if needed in the app)
+*.jpg
+*.jpeg
+*.png
+image.jpg
+
+# Temporary files
+*.pickle
+token.pickle
+
+# Scripts
+*.sh
+
+# Logs
+*.log

.gitignore

@@ -0,0 +1,182 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+dooms_day.sh
+/dooms_day.sh
+dooms_day.sh/
+dooms_day.sh*
+/Story Sessions
+/Story-Generation
+asd/
+/asd/
+/asd
+# C extensions
+*.so
+venv
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

.idea/.gitignore

@@ -0,0 +1,5 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/

.idea/Hekaya3.iml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="inheritedJdk" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+  <component name="PyDocumentationSettings">
+    <option name="format" value="GOOGLE" />
+    <option name="myDocStringFormat" value="Google" />
+  </component>
+</module>

.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,19 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+    <inspection_tool class="JSHint" enabled="true" level="ERROR" enabled_by_default="true" />
+    <inspection_tool class="JupyterPackageInspection" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="PyInterpreterInspection" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="PyPackageRequirementsInspection" enabled="false" level="WARNING" enabled_by_default="false" />
+    <inspection_tool class="PyPep8NamingInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true">
+      <option name="ignoredErrors">
+        <list>
+          <option value="N806" />
+        </list>
+      </option>
+    </inspection_tool>
+    <inspection_tool class="PyShadowingNamesInspection" enabled="true" level="TEXT ATTRIBUTES" enabled_by_default="true" editorAttributes="CONSIDERATION_ATTRIBUTES" />
+    <inspection_tool class="PyUnresolvedReferencesInspection" enabled="false" level="WARNING" enabled_by_default="false" />
+  </profile>
+</component>

.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/Hekaya3.iml" filepath="$PROJECT_DIR$/.idea/Hekaya3.iml" />
+    </modules>
+  </component>
+</project>

.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="" vcs="Git" />
+  </component>
+</project>

Dockerfile

@@ -0,0 +1,34 @@
+# Use Python 3.10 slim image
+FROM python:3.10-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies for OpenCV and other libraries
+RUN apt-get update && apt-get install -y \
+    libgl1 \
+    libglib2.0-0 \
+    libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application files
+COPY . .
+
+# Create necessary directories
+RUN mkdir -p content Story-Generation
+
+# Expose Gradio default port
+EXPOSE 7860
+
+# Set environment variables for Gradio
+ENV GRADIO_SERVER_NAME="0.0.0.0"
+ENV GRADIO_SERVER_PORT=7860
+
+# Run the application
+CMD ["python", "app.py"]

LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

TimeLog.md

@@ -0,0 +1,34 @@
+# Key Performance Insights
+
+## 🔴 Slowest Functions
+- **generate_direct_comic**: 118.74s total (2 calls, avg 59.37s)  
+- **generate_comic**: 76.33s total (2 calls, avg 38.16s)  
+- **generate_image_fn**: 76.20s total (2 calls, avg 38.10s)  
+- **generate_image_narration**: 36.40s total (2 calls, avg 18.20s)  
+
+## 🟡 Medium Duration Functions
+- **enhance_user_story**: 10.01s total (6 calls, avg 1.67s)  
+- **extract_comic_scenes**: 2.71s total (2 calls, avg 1.35s)  
+
+## 🟢 Fast Functions
+- All other functions executed in **milliseconds (< 0.01s each)**  
+
+---
+
+# Notable Observations
+
+- **Huge Performance Difference**:  
+  The second run of `generate_image_fn` took **73.82s** vs only **2.38s** in the first run – likely due to the API error in the first attempt vs successful generation in the second.  
+
+- **Error Impact**:  
+  The first `generate_direct_comic` run (**22.15s**) was much faster than the second (**96.58s**) because the first failed at image generation due to the OpenAI verification error.  
+
+- **Most Function Calls**:  
+  `enhance_user_story` and `_create_detail_focused_enhancement_prompt` were called **6 times each**, indicating retry logic during the enhancement process.  
+
+- **Total Runtime**:  
+  The entire process took approximately **5.35 minutes (320.39s)** across **48 function calls**.  
+
+---
+
+⚠️ **Main Bottleneck**: The **image generation and processing pipeline** accounts for **over 90%** of the total execution time.

TimeLog2.md

@@ -0,0 +1,50 @@
+# ⏱️ Story Generation Time Log
+
+---
+
+## ✨ Story Enhancement
+- 📝 **_create_detail_focused_enhancement_prompt (1)** → 0.0000s  
+- 📝 **_create_detail_focused_enhancement_prompt (2)** → 0.0000s  
+- 📝 **_create_detail_focused_enhancement_prompt (3)** → 0.0000s  
+- 🚀 **enhance_user_story (final)** → 0.0005s  
+- ⏳ **enhance_user_story (attempt span)** → 2.0014s  
+- ⏳ **enhance_user_story (overall span)** → 3.0035s  
+
+---
+
+## 🏗️ Layout & Description Generation
+- 🔢 **_find_all_factorizations** → 0.0000s  
+- 🧮 **_calculate_optimal_layout** → 0.0000s  
+- 📐 **_calculate_optimal_grid_layout** → 0.0010s  
+- 📝 **_get_optimal_layout_description** → 0.0010s  
+- 📖 **_create_detailed_story_description** → 0.0000s  
+- 🎨 **_get_enhanced_style_specifications** → 0.0000s  
+- 🔢 **_find_all_factorizations (2nd)** → 0.0000s  
+- 🧮 **_calculate_optimal_layout (2nd)** → 0.0000s  
+- 📐 **_calculate_optimal_grid_layout (2nd)** → 0.0000s  
+- 📊 **_create_comprehensive_technical_specifications** → 0.0010s  
+- 🛠️ **_create_advanced_quality_and_flow_instructions** → 0.0000s  
+- ✂️ **_assemble_prompt_with_smart_truncation** → 0.0000s  
+- 🖼️ **_create_comic_prompt** → 0.0020s  
+
+---
+
+## 🎨 Comic Generation
+- 🖌️ **generate_image_fn** → 69.6515s  
+- 🎭 **generate_comic** → 69.7712s  
+- 🎤 **generate_image_narration** → 29.2157s  
+- 📚 **generate_direct_comic** → 101.9924s  
+
+---
+
+## 📸 Scene Extraction
+- 🗂️ **extract_comic_scenes (1st run)** → 2.4218s  
+- 🗂️ **extract_comic_scenes (2nd run)** → 2.7060s  
+
+---
+
+# 📊 Performance Overview
+- ✨ **Enhancement Total:** ~3.0s  
+- 🏗️ **Layout/Description Total:** ~0.005s  
+- 🎨 **Comic Generation Total:** ~201.6s  
+- 📸 **Scene Extraction Total:** ~5.1s  

app.py

@@ -0,0 +1,102 @@
+import os
+import gradio as gr
+from google.generativeai import configure
+from ui.story_interface import create_story_interface
+import config
+
+def main():
+    # Configure Google API
+    configure(api_key=config.GOOGLE_API_KEY)
+
+    # Custom CSS for better narration display
+    custom_css = """
+    .story-narration-box {
+        background: linear-gradient(135deg, #f8fafc 0%, #e2e8f0 100%) !important;
+        border: 3px solid #6366f1 !important;
+        border-radius: 16px !important;
+        padding: 24px !important;
+        margin: 24px 0 !important;
+        box-shadow: 0 8px 20px rgba(99, 102, 241, 0.15) !important;
+        line-height: 1.8 !important;
+        color: #1e293b !important;
+        font-size: 16px !important;
+        min-height: 120px !important;
+    }
+
+    .story-narration-box h3 {
+        color: #4338ca !important;
+        border-bottom: 3px solid #6366f1 !important;
+        padding-bottom: 12px !important;
+        margin-bottom: 20px !important;
+        font-size: 20px !important;
+        font-weight: bold !important;
+        text-align: center !important;
+    }
+
+    .story-narration-box p {
+        margin-bottom: 16px !important;
+        text-align: left !important;
+        color: #334155 !important;
+        font-size: 16px !important;
+        line-height: 1.7 !important;
+        font-weight: 500 !important;
+    }
+
+    .story-narration-box div {
+        color: #334155 !important;
+        font-size: 16px !important;
+    }
+
+    #story_narration {
+        max-height: 600px !important;
+        overflow-y: auto !important;
+        border: 2px solid #e2e8f0 !important;
+        border-radius: 12px !important;
+        background-color: #f8fafc !important;
+    }
+
+    #scene_narration {
+        max-height: 500px !important;
+        overflow-y: auto !important;
+        border: 2px solid #e2e8f0 !important;
+        border-radius: 12px !important;
+    }
+
+    /* Ensure all text in narration boxes is visible and prominent */
+    #story_narration *, #scene_narration * {
+        color: #334155 !important;
+        font-size: 16px !important;
+    }
+
+    #story_narration h3, #scene_narration h3 {
+        color: #4338ca !important;
+        font-size: 20px !important;
+        text-align: center !important;
+    }
+
+    /* Style for quick narration lines */
+    .story-narration-box em {
+        color: #64748b !important;
+        font-style: italic !important;
+        text-align: center !important;
+        display: block !important;
+        margin: 20px 0 !important;
+    }
+    """
+
+    # Create and launch the Gradio interface
+    with gr.Blocks(
+        theme=gr.themes.Soft(primary_hue="indigo", secondary_hue="blue"),
+        css=custom_css
+    ) as demo:
+        create_story_interface(demo)
+
+    demo.launch(
+    server_name="0.0.0.0",  # Allows external access
+    server_port=7860,
+    share=False,  # Set to True if you want a public link
+    debug=True
+)
+
+if __name__ == "__main__":
+    main()

config.py

@@ -0,0 +1,35 @@
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+GOOGLE_API_KEY = os.environ.get("GOOGLE_API_KEY")
+OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")
+TOGETHER_API_KEY = os.environ.get("TOGETHER_API_KEY")
+BFL_API_KEY = os.environ.get("BFL_API_KEY")
+IMAGE_STYLE_INFO = {
+    "Comic Book Style": "Professional comic book art with bold outlines, vibrant colors, and dynamic action poses. Perfect for multi-panel consistency with uniform character designs across panels.",
+    "Manga Style": "Japanese manga aesthetic with distinctive toning, speed lines, and expressive character eyes. Excellent consistency for sequential storytelling with consistent character designs.",
+    "Cartoon Style": "Animated cartoon style with exaggerated features, bright colors, and simplified designs. Ideal for maintaining character consistency across multiple panels in one image.",
+    "Photorealistic": "Highly detailed photographic quality with accurate lighting, textures, and proportions. Consistent realistic style perfect for single-image multi-panel storytelling.",
+    "Cinematic Realism": "Movie-like visuals with dramatic lighting, depth of field, and realistic composition. Cinematic consistency across panels with unified lighting and color grading.",
+    "Digital Painting": "Digital art with realistic elements but visible brushwork and artistic interpretation. Consistent artistic style throughout multi-panel compositions."
+}
+
+IMAGE_STYLES = list(IMAGE_STYLE_INFO.keys())
+
+DEFAULT_COMIC_SETTINGS = {
+    "num_panels": 12, 
+    "max_scenes": 12, 
+    "image_style": "Comic Book Style"
+}
+
+AGE_GROUP_INFO = {
+    "3-5 (Pre-school)": "Very simple vocabulary, short sentences, playful tone suitable for pre-school children.",
+    "6-8 (Kids)": "Simple vocabulary and sentences with lively, descriptive language for early readers.",
+    "9-12 (Pre-teen)": "Balanced vocabulary with engaging narrative style appropriate for pre-teens.",
+    "13-18 (Teen)": "Richer vocabulary, deeper themes and emotions suitable for teenagers.",
+    "18+ (Adult)": "Full vocabulary, complex themes, and immersive detail suitable for adults."
+}
+
+AGE_GROUPS = list(AGE_GROUP_INFO.keys())

handover.md

@@ -0,0 +1,244 @@
+# Comic Story Generator: Code Handover Document
+
+**Date:** 2025-7-22
+**Document Purpose:** This document provides a comprehensive technical handover for the Comic Story Generator project. It is intended for developers and future maintainers responsible for the deployment, maintenance, and extension of the application.
+
+---
+
+## 1. Project Overview
+
+The Comic Story Generator is a web application that automatically creates multi-page, textless comic stories from a user-provided description. The application leverages generative AI to produce visually coherent narratives, focusing on character consistency, expressive emotion, and logical panel sequencing.
+
+### 1.1. Core Functionality
+
+The application is designed to translate a textual story concept into a purely visual comic strip. Key characteristics include:
+
+*   **AI-Powered Narrative:** Utilizes Google's Gemini to interpret the user's concept and break it down into a structured, panel-by-panel narrative.
+*   **Visual Generation:** Employs a GPT-based image model to render complete comic pages based on the AI-generated narrative structure.
+*   **Intelligent Panel Detection:** Uses Gemini Vision to analyze the generated full-page image and accurately detect the boundaries of each panel, ensuring precise splitting.
+*   **Customization:** Offers users control over the output, including:
+    *   **Layout:** Choice of panel count (from 4 to 24).
+    *   **Length:** Generation of 1 to 10 pages.
+    *   **Art Style:** A selection of visual styles, including "Classic Comic," "Manga," "Cartoon," "Digital Paint," and a high-contrast "Accessible" style designed for users with special needs.
+
+### 1.2. High-Level Workflow
+
+The generation process follows a clear, multi-step pipeline:
+
+1.  **User Input:** The user submits a short description of the desired story.
+2.  **Story Generation:** The `StoryGenerator` component uses Gemini to create a detailed, scene-by-scene description for each comic panel.
+3.  **Page Generation:** The `ComicGenerator` takes the panel descriptions and instructs the GPT-Image model to generate a single, composite image representing a full comic page with panels arranged in a grid.
+4.  **Layout Analysis:** The generated page is passed to the `GeminiVision` component, which analyzes the image to identify the precise coordinates and boundaries of each panel.
+5.  **Panel Splitting:** The application uses the coordinates from the vision analysis to accurately split the composite image into individual panel images.
+6.  **Final Output:** The processed panels are presented to the user as a complete, multi-page visual story.
+
+---
+
+## 2. System Architecture
+
+The application is built on a modular architecture composed of three primary classes, each responsible for a distinct part of the generation pipeline.
+
+### 2.1. System Diagram
+
+```mermaid
+classDiagram
+    class StoryGenerator{
+        +generate_story(description: string) : list[string]
+        +enhance_visuals(panel_descriptions: list) : list[string]
+    }
+    class ComicGenerator{
+        +generate_page(panel_descriptions: list) : Image
+        +split_panels(page_image: Image, grid_layout: dict) : list[Image]
+    }
+    class GeminiVision{
+        +analyze_layout(page_image: Image) : dict
+    }
+    
+    StoryGenerator "1" -- "1" ComicGenerator : Provides panel descriptions
+    ComicGenerator "1" -- "1" GeminiVision : Uses for layout analysis
+```
+
+### 2.2. Data Flow
+
+The end-to-end data flow illustrates the interaction between the user, the application, and the underlying AI models.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant App
+    participant Gemini as Gemini (Text/Story)
+    participant GPTImage as GPT-Image (Visuals)
+    participant GeminiVision as Gemini Vision (Analysis)
+
+    User->>+App: Submits story description
+    App->>+Gemini: Requests story structure from description
+    Gemini-->>-App: Returns panel-by-panel text descriptions
+    App->>+GPTImage: Requests comic page generation from descriptions
+    GPTImage-->>-App: Returns single full-page image
+    App->>+GeminiVision: Requests layout analysis of the image
+    GeminiVision-->>-App: Returns coordinates of each panel
+    App->>User: Displays final, split-panel comic
+```
+
+---
+
+## 3. Setup & Installation
+
+### 3.1. Prerequisites
+
+*   **Python:** Version 3.9 or higher.
+*   **API Keys:**
+    *   An active OpenAI API key.
+    *   An active Google API key with access to the Gemini family of models.
+
+### 3.2. Installation Steps
+
+1.  **Clone the Repository:**
+    ```bash
+    git clone https://github.com/yourusername/Comic-Story-Generator.git
+    cd Comic-Story-Generator
+    ```
+
+2.  **Create and Activate a Virtual Environment:**
+    ```bash
+    # Create the environment
+    python -m venv venv
+    
+    # Activate the environment (macOS/Linux)
+    source venv/bin/activate
+    
+    # Or, activate on Windows
+    # venv\Scripts\activate
+    ```
+
+3.  **Install Dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+4.  **Configure Environment Variables:**
+    Create a `.env` file in the project root and add your API keys.
+    ```bash
+    echo "OPENAI_API_KEY=your_openai_key" > .env
+    echo "GOOGLE_API_KEY=your_google_key" >> .env
+    ```
+    *Note: Ensure the `.env` file is added to your `.gitignore` file to prevent committing secrets.*
+
+---
+
+## 4. Environment Variables / Secrets
+
+The application requires the following environment variables to be set in a `.env` file at the project's root.
+
+| Variable | Description | Required | Example |
+| :--- | :--- | :--- | :--- |
+| `OPENAI_API_KEY` | API key for the OpenAI service, used for GPT-Image generation. | Yes | `sk-xxxxxxxxxxxxxxxxxxxxxxxx` |
+| `GOOGLE_API_KEY` | API key for Google AI services, used for Gemini (story structure) and Gemini Vision (layout analysis). | Yes | `AIzaSyxxxxxxxxxxxxxxxxxxxxx` |
+
+---
+
+## 5. How to Run
+
+After completing the setup and installation steps, launch the application with the following command from the project's root directory:
+
+```bash
+python app.py
+```
+
+The application will start a local web server, and the interface will be accessible at the URL provided in the console (typically `http://127.0.0.1:7860`).
+
+---
+
+## 6. Deployment Instructions
+
+[TODO] This section requires documentation for deploying the application to a production environment. Steps should include:
+*   Recommended hosting provider (e.g., AWS, Heroku, DigitalOcean).
+*   Instructions for setting up a production-grade web server (e.g., Gunicorn).
+*   Configuration of a reverse proxy (e.g., Nginx).
+*   Management of production environment variables/secrets.
+*   Process management (e.g., using `systemd`).
+
+---
+
+## 7. Core Components & Logic
+
+The application logic is encapsulated in three main classes.
+
+### 7.1. `StoryGenerator`
+
+*   **Responsibility:** Handles the narrative creation phase.
+*   **`generate_story()`:** Takes the raw user description as input. It constructs a prompt for the Gemini model to elicit a structured response containing a list of detailed text descriptions, one for each comic panel.
+*   **`enhance_visuals()`:** Processes the panel descriptions to add specific visual cues and optimizations, particularly for the "Accessible" style, ensuring high contrast and simplified object representation.
+
+### 7.2. `ComicGenerator`
+
+*   **Responsibility:** Manages the visual generation and processing of the comic page.
+*   **`generate_page()`:** Aggregates the panel descriptions from `StoryGenerator` into a single, complex prompt for the GPT-Image model. This prompt instructs the AI to create one composite image with all panels laid out in a grid.
+*   **`split_panels()`:** Receives the generated page image and the layout data from `GeminiVision`. It uses this data to crop the page into individual panel images with high precision.
+
+### 7.3. `GeminiVision`
+
+*   **Responsibility:** Performs visual analysis on the generated comic page.
+*   **`analyze_layout()`:** This is the core of the intelligent panel-splitting feature. It takes the full-page image as input and uses the Gemini Vision model to visually identify the boundaries of each panel. It returns a dictionary containing the coordinates and dimensions of the detected grid, which is more robust than assuming a fixed grid layout.
+
+---
+
+## 8. Third-party Dependencies
+
+The complete list of Python packages is specified in `requirements.txt`. Key dependencies include:
+
+*   **`openai`**: Python client for the OpenAI API.
+*   **`google-generativeai`**: Python client for the Google AI (Gemini) API.
+*   **`python-dotenv`**: For loading environment variables from the `.env` file.
+*   **`Pillow`**: For image manipulation (cropping and saving).
+*   **[Info Needed]**: The web framework used to build `app.py` (e.g., `gradio`, `flask`, `fastapi`).
+
+---
+
+## 9. Testing Instructions
+
+[TODO] A testing framework has not been established for this project. Future work should include:
+*   **Test Suite Setup:** Choose and configure a testing framework (e.g., `pytest`).
+*   **Unit Tests:** Create unit tests for individual methods in `StoryGenerator`, `ComicGenerator`, and `GeminiVision`. This should involve mocking the API calls to AI services to test the data processing logic in isolation.
+*   **Integration Tests:** Develop tests for the entire generation pipeline, from user input to final split panels.
+*   **Continuous Integration:** Set up a CI pipeline (e.g., using GitHub Actions) to run tests automatically on pull requests.
+
+---
+
+## 10. Troubleshooting & Common Issues
+
+[TODO] This section should be populated as common issues are identified. Potential areas to document include:
+*   **API Key Errors:** Steps to verify that API keys are correctly configured and have the necessary permissions.
+*   **Incoherent Stories:** Guidance on how to write effective initial descriptions to improve narrative quality.
+*   **Poor Panel Splitting:** Troubleshooting steps for when Gemini Vision fails to detect the layout correctly (e.g., checking image complexity, trying a different art style).
+*   **Long Generation Times:** Explanation of typical performance and factors that can cause delays (e.g., API provider latency, number of panels).
+
+---
+
+## 11. TODOs / Future Work
+
+Based on the project's focus areas, the following are key areas for future development and contribution:
+
+*   **Core Generation Logic:**
+    *   Improve character consistency across multiple pages.
+    *   Experiment with different AI models for potentially better visual or narrative results.
+    *   Add support for including text (dialogue, captions) as an optional feature.
+*   **UI/UX Enhancements:**
+    *   Develop a more interactive interface for viewing and arranging panels.
+    *   Allow users to regenerate individual panels without restarting the entire process.
+    *   Add an option to export the final comic as a PDF or other formats.
+*   **Accessibility Improvements:**
+    *   Further refine the "Accessible" art style based on user feedback.
+    *   Implement ARIA attributes and ensure full keyboard navigability for the web interface.
+    *   Add an "image description" feature where a text-to-speech engine can describe the generated panels.
+*   **Documentation:**
+    *   Create a detailed API reference for developers looking to build on the platform.
+    *   Write user-facing guides on how to get the best results from the generator.
+
+---
+
+## 12. Contact / Ownership Info
+
+*   **Source Code:** [https://github.com/yourusername/Comic-Story-Generator](https://github.com/yourusername/Comic-Story-Generator)
+*   **License:** This project is licensed under the **MIT License**. For full details, see the `LICENSE` file in the repository.
+*   **Primary Contact:** [Info Needed: Add primary maintainer's name and contact information (e.g., GitHub handle or email).]

kill.sh

@@ -0,0 +1,4 @@
+#!/bin/bash
+
+echo "Killing all Python processes..."
+pkill -f python

models/comic_image_generator.py

@@ -0,0 +1,1292 @@
+import io
+import base64
+import os
+from PIL import Image, ImageDraw, ImageFont
+import config
+import warnings
+import textwrap
+from pathlib import Path
+import time
+from models.image_generation import generate_image_fn
+from google.generativeai import GenerativeModel
+import json
+import re
+import tempfile
+import shutil
+from google.generativeai.types import GenerationConfig
+from utils.comic_panel_splitter import split_comic_panels
+import cv2
+import numpy as np
+from datetime import datetime
+warnings.filterwarnings("ignore", message="IMAGE_SAFETY is not a valid FinishReason")
+
+
+def log_execution(func):
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        start_str = datetime.fromtimestamp(start_time).strftime('%Y-%m-%d %H:%M:%S')
+        
+        result = func(*args, **kwargs)
+        
+        end_time = time.time()
+        end_str = datetime.fromtimestamp(end_time).strftime('%Y-%m-%d %H:%M:%S')
+        duration = end_time - start_time
+        
+        # Write to file (works in Colab)
+        with open('content/logs.txt', 'a') as f:
+            f.write(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s\n")
+        
+        # Also print to see output immediately
+        print(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s")
+        
+        return result
+    return wrapper
+
+class ComicImageGenerator:
+    """
+    Generates a comic-style image.
+    """
+
+    def __init__(self):
+        pass
+    
+    
+    @log_execution
+    def generate_comic(self, story_data, output_path=None, style=None):
+        """
+        Generate a comic-style image based on the provided story data.
+
+        Args:
+            story_data: Dictionary containing the story information
+            output_path: Optional path to save the resulting image
+            style: Optional comic style to use
+
+        Returns:
+            PIL.Image.Image: The comic image
+            str: Base64 encoded data URL of the image
+        """
+        title = story_data.get("title", "My Story")
+        description = story_data.get("description", "")
+        characters = story_data.get("characters", [])
+        settings = story_data.get("settings", [])
+        num_scenes = 9
+
+        prompt = self._create_comic_prompt(title, description, characters, settings, style, num_scenes)
+
+        try:
+            print(f"Generating comic with {num_scenes} scenes...")
+
+            comic_image = generate_image_fn(
+                selected_prompt=prompt,
+                output_path=output_path
+            )
+
+            if comic_image is None:
+                comic_image = self._create_placeholder_comic(title, description)
+
+                if output_path:
+                    directory = os.path.dirname(output_path)
+                    if directory and not os.path.exists(directory):
+                        os.makedirs(directory)
+                    comic_image.save(output_path)
+
+            buffered = io.BytesIO()
+            comic_image.save(buffered, format="PNG")
+            img_bytes = buffered.getvalue()
+            img_b64 = base64.b64encode(img_bytes).decode("utf-8")
+            data_url = f"data:image/png;base64,{img_b64}"
+
+            return comic_image, data_url
+
+        except Exception as e:
+            print(f"Error generating comic: {str(e)}")
+            placeholder = self._create_placeholder_comic(title, description)
+
+            if output_path:
+                directory = os.path.dirname(output_path)
+                if directory and not os.path.exists(directory):
+                    os.makedirs(directory)
+                placeholder.save(output_path)
+
+            buffered = io.BytesIO()
+            placeholder.save(buffered, format="PNG")
+            img_bytes = buffered.getvalue()
+            img_b64 = base64.b64encode(img_bytes).decode("utf-8")
+            data_url = f"data:image/png;base64,{img_b64}"
+
+            return placeholder, data_url
+        
+    @log_execution
+    def _create_comic_prompt(self, title, description, characters=None, settings=None, style=None, num_scenes=1):
+        """
+        Create a sophisticated, optimized prompt for comic generation with advanced visual consistency techniques.
+        Specialized for high-quality multi-panel storytelling with perfect character continuity.
+
+        Args:
+            title: Title of the story
+            description: Visual description of the story
+            characters: List of character data
+            settings: List of setting data
+            style: Optional visual style
+            num_scenes: Number of scenes to include (1-24)
+
+        Returns:
+            str: Advanced prompt optimized for professional comic generation with smart detail preservation
+        """
+
+        priority_sections = []
+
+        layout_specs = self._get_optimal_layout_description(num_scenes)
+        priority_sections.append(f"CRITICAL LAYOUT: {layout_specs}")
+
+        if num_scenes >= 20:
+            compact_instructions = [
+                "🎯 COMPACT SCENE MASTERY FOR 20 PANELS:",
+                "SMALL EFFICIENT SCENES: Each panel must tell its story moment with maximum visual economy - focus on ONE key action, emotion, or story beat per panel",
+                "CLEAR FOCAL POINTS: Every panel needs ONE main subject in sharp focus with minimal background distractions",
+                "ESSENTIAL ELEMENTS ONLY: Include only the most crucial visual elements needed to advance the story - remove ALL unnecessary details",
+                "READABLE AT SMALL SIZE: No text text, expressions, and actions must be clearly visible even when the panel is small - use bold, simple compositions"
+            ]
+            priority_sections.extend(compact_instructions)
+
+        if characters:
+            character_details = self._create_detailed_character_specifications(characters, num_scenes)
+            priority_sections.extend(character_details)
+
+        enhanced_story = self._create_detailed_story_description(description, title)
+        priority_sections.append(enhanced_story)
+
+        if settings:
+            environment_details = self._create_detailed_environment_specifications(settings, num_scenes)
+            priority_sections.extend(environment_details)
+
+        technical_specs = self._create_comprehensive_technical_specifications(style, num_scenes)
+        priority_sections.extend(technical_specs)
+
+        quality_flow = self._create_advanced_quality_and_flow_instructions(num_scenes)
+        priority_sections.extend(quality_flow)
+
+        assembled_prompt = self._assemble_prompt_with_smart_truncation(priority_sections)
+        
+        if self.generate_panel_descriptions(assembled_prompt):
+            final_prompt = self.generate_panel_descriptions(assembled_prompt)
+        else : 
+            final_prompt = assembled_prompt
+
+        print(f"\n XXXXXX {final_prompt} XXXXXX \n")
+
+        return final_prompt
+    
+    @log_execution
+    def _create_detailed_character_specifications(self, characters, num_scenes):
+        """Create extremely detailed character specifications prioritizing visual consistency."""
+        char_specs = []
+
+        char_specs.append("🎭 CRITICAL CHARACTER CONSISTENCY PROTOCOL:")
+        char_specs.append("ABSOLUTE REQUIREMENT: Characters MUST look identical in every single panel - same face, hair, clothes, proportions, expressions style")
+
+        for i, character in enumerate(characters[:3]):  
+            if isinstance(character, dict) and "visual_description" in character:
+                char_name = character.get("name", f"Character_{i+1}")
+                char_desc = character["visual_description"]
+
+                char_spec = f"CHARACTER {i+1} - {char_name}: {char_desc}"
+
+                if "traits" in character and character["traits"]:
+                    traits = character["traits"][:5]  
+                    char_spec += f" | DISTINCTIVE FEATURES: {', '.join(traits)}"
+
+                char_spec += f" | CONSISTENCY RULE: This exact appearance must be maintained across all {num_scenes} panels with zero variation in facial features, hair, clothing, or body proportions"
+
+                char_specs.append(char_spec)
+
+        if len([c for c in characters[:3] if isinstance(c, dict) and 'visual_description' in c]) > 1:
+            char_specs.append(f"MULTI-CHARACTER RULE: All characters must maintain their exact individual appearances simultaneously across all {num_scenes} panels - no character design drift allowed")
+
+        return char_specs
+    
+    @log_execution
+    def _create_detailed_story_description(self, description, title):
+        """Create enhanced story description with preserved important details."""
+        story_elements = []
+
+        enhanced_desc = f"STORY CONTENT: {title} - {description}"
+
+        enhanced_desc += " | VISUAL NARRATIVE FOCUS: Every detail must be clearly visible and contribute to story comprehension through imagery alone"
+
+        enhanced_desc += " | ATMOSPHERIC DETAILS: Include specific lighting, weather, time of day, and environmental mood indicators that enhance the narrative"
+
+        enhanced_desc += " | CHARACTER EXPRESSION CLARITY: All emotions, reactions, and character intentions must be immediately readable through facial expressions, body language, and positioning"
+
+        return enhanced_desc
+    @log_execution
+    def _create_detailed_environment_specifications(self, settings, num_scenes):
+        """Create detailed environment specifications with consistency focus."""
+        env_specs = []
+
+        env_specs.append(" ENVIRONMENTAL CONSISTENCY PROTOCOL:")
+
+        for i, setting in enumerate(settings[:3]):  
+            if isinstance(setting, dict) and "description" in setting:
+                setting_name = setting.get("name", f"Location_{i+1}")
+                setting_desc = setting["description"]
+
+                env_spec = f"LOCATION {i+1} - {setting_name}: {setting_desc}"
+
+                if "visual_elements" in setting and setting["visual_elements"]:
+                    elements = setting["visual_elements"][:5]  
+                    env_spec += f" | KEY VISUAL MARKERS: {', '.join(elements)}"
+
+                if "mood" in setting:
+                    env_spec += f" | ATMOSPHERE: {setting['mood']}"
+
+                env_spec += f" | LOCATION CONSISTENCY: When this location appears across multiple panels, all architectural details, lighting, and distinctive features must remain identical"
+
+                env_specs.append(env_spec)
+
+        return env_specs
+    @log_execution
+    def _create_comprehensive_technical_specifications(self, style, num_scenes):
+        """Create comprehensive technical specifications with detail preservation."""
+        tech_specs = []
+
+        style_details = self._get_enhanced_style_specifications(style)
+        tech_specs.extend(style_details)
+
+        composition_specs = [
+            " PANEL COMPOSITION MASTERY:",
+            f"Grid Layout: Precisely arranged {self._calculate_optimal_grid_layout(num_scenes)} grid with professional comic book spacing and clear panel borders",
+            "Visual Hierarchy: Each panel must have a clear focal point with supporting details that enhance rather than distract from the main action",
+            "Depth and Perspective: Use foreground, midground, and background elements to create visual depth and spatial relationships",
+            "Color Harmony: Maintain consistent color palette across all panels while using color psychology to enhance mood and narrative flow"
+        ]
+
+        if num_scenes >= 20:
+            composition_specs.extend([
+                "COMPACT PANEL OPTIMIZATION: Design each panel for MAXIMUM visual impact in minimal space",
+                "SIMPLE BACKGROUNDS: Use minimal, clean backgrounds that don't compete with main subjects",
+                "BOLD CHARACTER POSES: Use clear, distinctive poses and gestures that read well at small sizes",
+                "HIGH CONTRAST: Ensure strong contrast between characters and backgrounds for clarity"
+            ])
+
+        tech_specs.extend(composition_specs)
+
+        detail_specs = [
+            " DETAIL PRESERVATION PROTOCOL:",
+            "Facial Detail Consistency: All character faces must maintain identical features - eye shape, nose structure, mouth proportions, facial hair, scars, or distinctive marks",
+            "Clothing and Accessory Continuity: Every piece of clothing, jewelry, weapons, or accessories must appear identical across panels",
+            "Environmental Detail Tracking: Background objects, architectural elements, vegetation, and atmospheric effects must remain consistent when locations reappear",
+            "Lighting Continuity: Maintain logical light sources and shadow patterns that reflect time of day and weather conditions consistently"
+        ]
+        tech_specs.extend(detail_specs)
+
+        return tech_specs
+    @log_execution
+    def _get_enhanced_style_specifications(self, style):
+        """Get enhanced style specifications with technical details."""
+        enhanced_styles = {
+            "Comic Book Style": [
+                " MODERN DIGITAL COMIC BOOK STYLE (NO SKETCH LINES, NO DEFORMITIES):",
+                "Line Art: Bold, ultra-clean digital inking with consistent stroke weight—absolutely no rough sketch lines or unfinished strokes",
+                "Color Treatment: Vibrant, saturated colors with polished cel-shading and sharp highlights for a glossy modern finish",
+                "Shading: Precise digital shadows and highlights—avoid gradient banding or painterly strokes associated with traditional sketches",
+                "Panel Borders: Clean, geometric panel borders with consistent gutters and professional comic book page layout standards"
+            ],
+            "Manga Style": [
+                " MODERN DIGITAL MANGA STYLE (NO SKETCH LINES, NO DEFORMITIES):",
+                "Line Quality: Razor-sharp digital line work with deliberate varying weights—completely free of rough sketches",
+                "Character Design: Classic manga proportions rendered crisply with expressive eyes and flawless facial details—no distortions",
+                "Tone Work: High-resolution screentones and digitally applied hatching for a refined finish",
+                "Panel Layout: Dynamic panel flow with polished angles that enhance narrative pacing"
+            ],
+            "Photorealistic": [
+                " MODERN DIGITAL PHOTOREALISM (NO SKETCH LINES, NO DEFORMITIES):",
+                "Rendering Quality: Cinema-quality realistic rendering with accurate lighting physics and atmospheric effects—faces and limbs must appear intact and natural",
+                "Detail Level: Ultra-high detail textures with crisp edges—no painterly or sketch artefacts",
+                "Color Accuracy: Natural color grading with realistic skin tones, environmental colors, and accurate material reflectance",
+                "Depth of Field: Professional photography-style focus effects with realistic camera perspective and depth relationships"
+            ],
+            "Cinematic Realism": [
+                " MODERN DIGITAL CINEMATIC REALISM (NO SKETCH LINES, NO DEFORMITIES):",
+                "Film Quality: Movie-grade digital rendering with crisp edges and zero sketch artefacts",
+                "Color Grading: Cinematic color treatment with cohesive palette—maintain realistic skin and material fidelity",
+                "Camera Work: Dynamic camera angles translated into polished panel compositions",
+                "Lighting Design: Professional film lighting with atmospheric effects—ensure characters remain fully detailed, no distortions"
+            ]
+        }
+
+        return enhanced_styles.get(style, [
+            " MODERN DIGITAL COMIC ILLUSTRATION (NO SKETCH LINES, NO DEFORMITIES):",
+            "Professional Art: Gallery-quality digital illustration with masterful composition, color theory, and technical execution",
+            "Visual Clarity: Crystal-clear details with optimal contrast and saturation for maximum visual impact and readability",
+            "Artistic Consistency: Unified artistic approach across all panels maintaining consistent quality and style treatment—absolutely no sketch artefacts"
+        ])
+    @log_execution
+    def _create_advanced_quality_and_flow_instructions(self, num_scenes):
+        """Create advanced quality and flow instructions."""
+        quality_instructions = [
+            " ADVANCED QUALITY REQUIREMENTS:",
+            "Technical Excellence: Ultra-high resolution output with crisp details, optimal contrast, and professional-grade visual quality",
+            "Narrative Clarity: Every panel must advance the story visibly - clear cause and effect relationships between sequential panels",
+            # "Visual Flow: Smooth eye movement guidance from panel to panel using composition, character positioning, and visual elements",
+            "Line Art: Sharp digital lines, clean and precise, emphasizing dynamic movement and emotional clarity.",
+            "Emotional Impact: Each panel must convey specific emotions through character expressions, body language, and environmental mood"
+        ]
+
+        if num_scenes > 1:
+            flow_instructions = [
+                f" {num_scenes}-PANEL FLOW MASTERY:",
+                # "Sequential Continuity: Logical progression from panel to panel with clear temporal and spatial relationships",
+                "Action Sequences: Break complex actions into clear, understandable steps across multiple panels",
+                "Character Tracking: Maintain character positions and movements logically across panel transitions",
+                "Pacing Control: Balance action panels with character moments and environmental establishing shots for optimal narrative rhythm",
+                "EACH PANEL IS A DISTINCT SCENE : Each panel must depict a unique, self-contained moment or tableau from the story. No visual elements or action should flow directly from one panel to another" 
+            ]
+
+            if num_scenes >= 20:
+                flow_instructions.extend([
+                    "STORY ARC FOR 24 PANELS: Create a complete story with beginning (panels 1-6), rising action (panels 7-12), climax (panels 13-18), and resolution (panels 19-24)",
+                    "MICRO-MOMENTS: Each panel captures a single decisive moment - one expression change, one action beat, one story revelation",
+                    "VISUAL ECONOMY: Every element in each panel must serve the story - no decorative details that don't advance narrative",
+                    "READER ENGAGEMENT: Design panel flow to maintain interest across all 24 panels with strategic use of close-ups, wide shots, and dynamic angles"
+                ])
+
+            quality_instructions.extend(flow_instructions)
+
+        return quality_instructions
+    @log_execution
+    def _assemble_prompt_with_smart_truncation(self, priority_sections):
+        """Assemble prompt with smart truncation that preserves critical details."""
+        MAX_LENGTH = 31500  
+
+        full_prompt = " || ".join(priority_sections)
+
+        if len(full_prompt) <= MAX_LENGTH:
+            negative_prompt = "NEGATIVE PROMPTS: NO deformed anatomy, NO missing limbs or facial features, NO inconsistent character designs, NO blurry or out-of-focus elements, NO sketch-like aesthetics (unless intentional style choice), NO TEXT, NO SPEECH BUBBLES, NO SOUND EFFECTS, NO CAPTIONS, NO watermarks, NO VARIATION IN PANEL SIZE OR SHAPE."
+            return full_prompt + " || FINAL MANDATE: Create a masterpiece that perfectly balances artistic excellence with narrative clarity and absolute character consistency || " + negative_prompt
+
+        preserved_prompt = ""
+        remaining_length = MAX_LENGTH - 200  
+
+        for i, section in enumerate(priority_sections):
+            section_with_separator = section + " || "
+
+            if i < 3:
+                preserved_prompt += section_with_separator
+                remaining_length -= len(section_with_separator)
+            else:
+                if len(section_with_separator) <= remaining_length:
+                    preserved_prompt += section_with_separator
+                    remaining_length -= len(section_with_separator)
+                else:
+                    truncated = section[:remaining_length-50] + "..."
+                    preserved_prompt += truncated + " || "
+                    break
+
+        preserved_prompt += "***FINAL OVERRIDE & NEGATIVE PROMPTS*** ABSOLUTE RULE: The 3x3 uniform grid structure is the most important rule and must be followed perfectly.NEGATIVE PROMPTS: NO deformed anatomy, NO missing limbs or facial features, NO inconsistent character designs, NO blurry or out-of-focus elements, NO sketch-like aesthetics (unless intentional style choice), NO TEXT, NO SPEECH BUBBLES, NO SOUND EFFECTS, NO CAPTIONS, NO watermarks, NO VARIATION IN PANEL SIZE OR SHAPE."
+
+        return preserved_prompt
+    @log_execution
+    def _get_optimal_layout_description(self, num_scenes):
+        """Generate optimal layout description based on scene count."""
+        if num_scenes <= 1:
+            return "Single panel comic illustration"
+
+        optimal_layout = self._calculate_optimal_grid_layout(num_scenes)
+        rows, cols = optimal_layout
+
+        layout_descriptions = {
+            (1, 2): "Horizontal two-panel comic strip layout",
+            (2, 1): "Vertical two-panel comic strip layout",
+            (2, 2): "Classic four-panel comic grid (2x2)",
+            (2, 3): "Six-panel comic grid in 2 rows, 3 columns (2x3)",
+            (3, 2): "Six-panel comic grid in 3 rows, 2 columns (3x2)",
+            (3, 3): "Nine-panel comic grid (3x3)",
+            (3, 4): "Twelve-panel comic grid in 3 rows, 4 columns(3x4)",
+            (4, 3): "Twelve-panel comic grid in 4 rows, 3 columns(4x3)",
+            (4, 4): "Sixteen-panel comic grid (4x4)",
+            (4, 6): "Twenty-four panel COMPACT comic grid in 4 rows, 6 columns - SMALL EFFICIENT SCENES with maximum story density per panel (4x6)",
+            (6, 4): "Twenty-four panel COMPACT comic grid in 6 rows, 4 columns - SMALL EFFICIENT SCENES with vertical storytelling format (6x4)",
+            (3, 8): "Twenty-four panel COMPACT comic grid in 3 rows, 8 columns - SMALL EFFICIENT SCENES with cinematic widescreen format(3x8)",
+            (8, 3): "Twenty-four panel comic grid in 8 rows, 3 columns - vertical scroll format (8x3)"
+        }
+
+        layout_desc = layout_descriptions.get((rows, cols), f"{rows}x{cols} comic panel grid layout")
+
+        return f"COMIC LAYOUT: {layout_desc} with clear panel borders, consistent gutters, and professional comic book formatting"
+    @log_execution
+    def _enhance_description_for_visual_consistency(self, description): # No Use?
+        """Enhance the core description with visual consistency keywords."""
+        consistency_enhancers = [
+            "maintaining perfect visual consistency throughout all panels",
+            "identical character appearances across every scene",
+            "unified lighting and color palette",
+            "consistent artistic style and perspective"
+        ]
+
+        enhanced = f"STORY CONTENT: {description}. "
+        enhanced += "VISUAL CONSISTENCY REQUIREMENTS: " + ", ".join(consistency_enhancers)
+
+        return enhanced
+    @log_execution
+    def _create_character_consistency_anchors(self, characters, num_scenes): # No Use?
+        """Create sophisticated character consistency instructions."""
+        anchors = []
+
+        if characters:
+            anchors.append("CHARACTER CONSISTENCY ANCHORS:")
+
+            for i, character in enumerate(characters[:2]):  
+                if isinstance(character, dict) and "visual_description" in character:
+                    char_desc = character["visual_description"]
+
+                    anchor = f"Character {i+1}: {char_desc} - MUST appear IDENTICAL in every single panel with exact same: facial features, hair style, clothing, proportions, and distinctive visual elements"
+                    anchors.append(anchor)
+
+            if num_scenes > 1:
+                anchors.append(f"CRITICAL: All {len([c for c in characters[:2] if isinstance(c, dict) and 'visual_description' in c])} characters must look exactly the same across all {num_scenes} panels - same faces, same outfits, same proportions, same artistic rendering")
+
+        return anchors
+    @log_execution
+    def _create_environment_consistency_anchors(self, settings, num_scenes): # No Use?
+        """Create environmental consistency instructions."""
+        anchors = []
+
+        if settings:
+            anchors.append("ENVIRONMENTAL CONSISTENCY:")
+
+            for setting in settings:
+                if isinstance(setting, dict) and "description" in setting:
+                    setting_desc = setting["description"]
+                    anchors.append(f"Setting: {setting_desc} - maintain consistent architectural details, lighting, and atmospheric elements when this location appears")
+
+            if num_scenes > 1:
+                anchors.append(f"Ensure environmental continuity across all {num_scenes} panels with logical spatial relationships and consistent time-of-day lighting")
+
+        return anchors
+    @log_execution
+    def _create_advanced_style_instructions(self, style, num_scenes):
+        """Create advanced style instructions with technical specifications."""
+        instructions = []
+
+        advanced_style_map = {
+            "Comic Book Style": [
+                "modern digital comic book illustration style (no sketch-like strokes, no deformities)",
+                "bold ultra-clean line art with consistent stroke weight",
+                "vibrant saturated colors with polished highlights and shadows",
+                "dynamic panel compositions with varied camera angles",
+                "classic comic book rendering techniques executed with a contemporary digital finish"
+            ],
+            "Manga Style": [
+                "modern digital manga illustration style (no sketch artefacts, no deformities)",
+                "razor-sharp line work with deliberate varying weights",
+                "subtle color palette with high-resolution screentone effects",
+                "expressive character designs with flawless facial details",
+                "dynamic manga panel composition and flow"
+            ],
+            "Cartoon Style": [
+                "polished digital cartoon style (clean vectors, no sketch lines, no deformities)",
+                "smooth rounded character designs with appealing proportions",
+                "bright harmonious color schemes with soft lighting",
+                "clear readable expressions and body language",
+                "family-friendly visual appeal with consistent character models"
+            ],
+            "Photorealistic": [
+                "high-quality digital photorealism (no sketch artefacts, no deformities)",
+                "detailed realistic lighting and shadows",
+                "natural color grading with realistic materials and textures",
+                "cinematic composition with depth of field effects",
+                "professional photography-inspired visual quality"
+            ],
+            "Cinematic Realism": [
+                "digital cinematic realism (crisp, no sketch lines, no deformities)",
+                "dramatic lighting with atmospheric effects",
+                "rich color grading with cinematic color palette",
+                "dynamic camera angles and professional composition",
+                "film-quality character rendering and environmental detail"
+            ],
+            "Digital Painting": [
+                "masterful digital painting technique with a polished finish (no sketch lines, no deformities)",
+                "controlled painterly brushwork with intentional texture and depth",
+                "rich color harmony with sophisticated lighting",
+                "artistic composition with traditional painting principles",
+                "high-end digital art gallery quality"
+            ]
+        }
+
+        if style and style in advanced_style_map:
+            instructions.append("ARTISTIC STYLE SPECIFICATIONS:")
+            instructions.extend(advanced_style_map[style])
+        else:
+            instructions.extend([
+                "ARTISTIC STYLE: High-quality illustration with professional comic book aesthetics",
+                "clean precise line work with consistent artistic rendering",
+                "harmonious color palette with strategic lighting effects",
+                "polished visual presentation with attention to detail"
+            ])
+
+        if num_scenes > 1:
+            instructions.append(f"STYLE CONSISTENCY: Maintain identical artistic style, line weight, color saturation, and rendering quality across all {num_scenes} panels")
+
+        return instructions
+    @log_execution
+    def _create_panel_flow_instructions(self, num_scenes):
+        """Create instructions for optimal panel flow and transitions."""
+        flow_instructions = []
+
+        if num_scenes > 1:
+            flow_instructions.extend([
+                "PANEL FLOW AND TRANSITIONS:",
+                "create smooth visual flow from panel to panel following standard left-to-right, top-to-bottom reading order",
+                "design panel compositions that guide the eye naturally through the sequence",
+                "establish clear visual relationships between consecutive panels",
+                "use consistent perspective and scale to maintain spatial continuity",
+                "create visual rhythm through varied but harmonious panel compositions"
+            ])
+
+            if num_scenes >= 10:
+                flow_instructions.extend([
+                    "COMPREHENSIVE STORYTELLING FLOW: Design a compelling visual narrative that maintains engagement across all 12 panels",
+                    "balance action panels with character moments and environmental establishing shots",
+                    "create visual crescendos and quiet beats for optimal pacing",
+                    "ensure each panel contributes meaningfully to the overall story progression"
+                ])
+
+        return flow_instructions
+    @log_execution
+    def _create_quality_specifications(self, num_scenes):
+        """Create technical quality specifications."""
+        quality_specs = [
+            "TECHNICAL QUALITY REQUIREMENTS:",
+            "ultra-high resolution with crisp clean details",
+            "professional comic book production quality",
+            "optimal contrast and saturation for visual clarity",
+            "balanced composition with clear focal points in each panel",
+            "masterful use of negative space and visual hierarchy"
+        ]
+
+        if num_scenes > 1:
+            quality_specs.extend([
+                f"perfect grid alignment with consistent panel spacing across all {num_scenes} panels",
+                "clear panel borders with professional gutters and margins",
+                "unified visual presentation suitable for professional comic publication"
+            ])
+
+        return quality_specs
+    @log_execution
+    def _optimize_prompt_structure(self, prompt_parts):
+        """Optimize the prompt structure for maximum AI comprehension."""
+        structured_prompt = []
+
+        for i, part in enumerate(prompt_parts):
+            if isinstance(part, list):
+                structured_prompt.append(" | ".join(part))
+            else:
+                structured_prompt.append(part)
+
+        final_prompt = " || ".join(structured_prompt)
+
+        final_prompt += " || FINAL REQUIREMENT: Create a masterpiece-quality comic that perfectly balances artistic excellence with clear storytelling"
+
+        return final_prompt
+    @log_execution
+    def _calculate_optimal_grid_layout(self, num_scenes):
+        """Calculate the most visually appealing grid layout for the given number of scenes."""
+        optimal_layouts = {
+            1: (1, 1),
+            2: (1, 2),
+            3: (1, 3),
+            4: (2, 2),
+            5: (1, 5),
+            6: (2, 3),
+            7: (1, 7),
+            8: (2, 4),
+            9: (3, 3),
+            10: (2, 5),
+            11: (1, 11),
+            12: (3, 4),  
+            13: (1, 13),
+            14: (2, 7),
+            15: (3, 5),
+            16: (4, 4),
+            17: (1, 17),
+            18: (3, 6),
+            19: (1, 19),
+            20: (4, 5),
+            21: (3, 7),
+            22: (2, 11),
+            23: (1, 23),
+            24: (4, 6),  
+        }
+
+        return optimal_layouts.get(num_scenes, self._calculate_optimal_layout(num_scenes, 1024, 768))
+
+    def _create_placeholder_comic(self, title, description):
+        """
+        Create a placeholder comic if image generation fails.
+
+        Args:
+            title: Title of the comic
+            description: Visual description of the comic
+
+        Returns:
+            PIL.Image.Image: Placeholder comic image
+        """
+        width, height = 800, 600
+
+        comic = Image.new("RGB", (width, height), (255, 255, 255))
+        draw = ImageDraw.Draw(comic)
+
+        try:
+            title_font = ImageFont.truetype("Arial.ttf", 36)
+            desc_font = ImageFont.truetype("Arial.ttf", 18)
+        except IOError:
+            title_font = desc_font = ImageFont.load_default()
+
+        draw.text((20, 20), title, fill=(0, 0, 0), font=title_font)
+
+        draw.rectangle([50, 80, width-50, height-50], outline=(0, 0, 0), fill=(220, 220, 220))
+
+        if description:
+            max_chars = 300
+            short_desc = description[:max_chars] + "..." if len(description) > max_chars else description
+            wrapped_desc = textwrap.fill(short_desc, width=70)
+            draw.text((60, 100), wrapped_desc, fill=(0, 0, 0), font=desc_font)
+
+        return comic
+    @log_execution
+    def split_comic_into_scenes(self, comic_image, num_scenes, preferred_layout=None, use_gemini_analysis=True): # No Use?
+        """
+        Split a comic image into individual scenes using advanced analysis techniques.
+        Optimized for 12-panel layouts with sophisticated grid detection and quality validation.
+
+        Args:
+            comic_image: PIL.Image.Image object of the comic
+            num_scenes: Expected number of scenes (for context only, OpenCV script auto-detects)
+            preferred_layout: Optional tuple (rows, cols) to override automatic detection (Not used by OpenCV)
+            use_gemini_analysis: Whether to use Gemini Vision or OpenCV.
+                                 True for Gemini (default), False for OpenCV.
+
+        Returns:
+            list: List of PIL.Image.Image objects, one for each detected scene
+        """
+        if not isinstance(comic_image, Image.Image):
+            raise ValueError("comic_image must be a PIL.Image.Image object")
+
+        if num_scenes <= 1 and not use_gemini_analysis: 
+            if num_scenes <= 1:
+                 return [comic_image]
+
+        width, height = comic_image.size
+        print(f"🎯 Splitting {width}x{height} comic into scenes (Target: {num_scenes} scenes if using grid, auto-detect if OpenCV)...")
+
+        if use_gemini_analysis:
+            print("🔍 Analyzing comic layout with enhanced Gemini Vision...")
+            if preferred_layout:
+                rows, cols = preferred_layout
+                print(f"🎯 Using manual override for Gemini: {rows}×{cols} layout")
+            else:
+                rows, cols = self.analyze_comic_layout_with_enhanced_gemini(comic_image, num_scenes)
+
+            rows, cols = self._validate_and_optimize_layout(rows, cols, num_scenes, width, height)
+
+            actual_panels = rows * cols
+            print(f"✅ Using Gemini-derived {rows}×{cols} grid layout - will extract {min(actual_panels, num_scenes)} panels")
+
+            scenes = self._extract_scenes_with_quality_check(comic_image, rows, cols, num_scenes)
+
+            return scenes
+        else:
+            print("🔩 Using OpenCV for panel splitting...")
+            temp_dir = tempfile.mkdtemp()
+            temp_image_path = os.path.join(temp_dir, "source_comic.png")
+            panels_output_dir = os.path.join(temp_dir, "output_panels")
+
+            try:
+                comic_image.save(temp_image_path, "PNG")
+
+                split_comic_panels(temp_image_path, panels_output_dir)
+
+                extracted_scenes = []
+                if os.path.exists(panels_output_dir):
+                    panel_files = sorted([f for f in os.listdir(panels_output_dir) if f.startswith("panel_") and f.endswith(".png")])
+                    for panel_file in panel_files:
+                        try:
+                            panel_image_path = os.path.join(panels_output_dir, panel_file)
+                            img = Image.open(panel_image_path)
+                            extracted_scenes.append(img)
+                        except Exception as e:
+                            print(f"Error loading panel image {panel_file}: {e}")
+
+                if not extracted_scenes:
+                    print("⚠️ OpenCV panel splitter did not return any panels. Returning original image.")
+                    return [comic_image]
+
+                print(f"✅ OpenCV successfully extracted {len(extracted_scenes)} panels.")
+                return extracted_scenes
+
+            except Exception as e:
+                print(f"❌ Error during OpenCV panel splitting: {e}")
+                return [comic_image]
+            finally:
+                if os.path.exists(temp_dir):
+                    shutil.rmtree(temp_dir)
+    @log_execution
+    def _validate_and_optimize_layout(self, rows, cols, num_scenes, image_width, image_height):
+        """Validate and optimize the layout based on image properties and panel count."""
+        panel_width = image_width / cols
+        panel_height = image_height / rows
+        panel_aspect_ratio = panel_width / panel_height
+
+        if panel_width < 50 or panel_height < 50:
+            print(f"⚠️ Panels too small ({panel_width:.0f}x{panel_height:.0f}). Recalculating layout...")
+            return self._calculate_optimal_grid_layout(num_scenes)
+
+        if panel_aspect_ratio < 0.2 or panel_aspect_ratio > 5.0:
+            print(f"⚠️ Panel aspect ratio {panel_aspect_ratio:.2f} is extreme. Optimizing layout...")
+            return self._calculate_optimal_grid_layout(num_scenes)
+
+        if num_scenes == 12:
+            optimal_12_layouts = [(3, 4), (4, 3), (2, 6), (6, 2)]
+            current_layout = (rows, cols)
+
+            if current_layout not in optimal_12_layouts:
+                image_aspect = image_width / image_height
+                best_layout = (3, 4)  
+                best_score = float('inf')
+
+                for opt_rows, opt_cols in optimal_12_layouts:
+                    layout_aspect = opt_cols / opt_rows
+                    score = abs(layout_aspect - image_aspect)
+                    if score < best_score:
+                        best_score = score
+                        best_layout = (opt_rows, opt_cols)
+
+                print(f"📋 Optimizing 12-panel layout from {rows}×{cols} to {best_layout[0]}×{best_layout[1]}")
+                return best_layout
+
+        if num_scenes == 24:
+            optimal_24_layouts = [(4, 6), (6, 4), (3, 8), (8, 3)]
+            current_layout = (rows, cols)
+
+            if current_layout not in optimal_24_layouts:
+                image_aspect = image_width / image_height
+                best_layout = (4, 6)  
+                best_score = float('inf')
+
+                for opt_rows, opt_cols in optimal_24_layouts:
+                    layout_aspect = opt_cols / opt_rows
+                    score = abs(layout_aspect - image_aspect)
+                    if score < best_score:
+                        best_score = score
+                        best_layout = (opt_rows, opt_cols)
+
+                print(f"📋 Optimizing 24-panel layout from {rows}×{cols} to {best_layout[0]}×{best_layout[1]} for compact scenes")
+                return best_layout
+
+        return (rows, cols)
+    @log_execution
+    def _extract_scenes_with_quality_check(self, comic_image, rows, cols, num_scenes):
+        """Extract scenes with quality validation and enhancement."""
+        width, height = comic_image.size
+
+        scene_width = width // cols
+        scene_height = height // rows
+
+        margin = 2  
+
+        scenes = []
+        extracted_count = 0
+
+        for row in range(rows):
+            for col in range(cols):
+                if extracted_count >= num_scenes:
+                    break
+
+                x1 = max(0, col * scene_width - margin)
+                y1 = max(0, row * scene_height - margin)
+                x2 = min(width, (col + 1) * scene_width + margin)
+                y2 = min(height, (row + 1) * scene_height + margin)
+
+                scene = comic_image.crop((x1, y1, x2, y2))
+
+                if self._validate_scene_quality(scene):
+                    scenes.append(scene)
+                    extracted_count += 1
+                else:
+                    print(f"⚠️ Scene {extracted_count + 1} failed quality check, keeping anyway")
+                    scenes.append(scene)  
+                    extracted_count += 1
+
+            if extracted_count >= num_scenes:
+                break
+
+        print(f"✅ Successfully extracted {len(scenes)} scenes")
+        return scenes
+    @log_execution
+    def _validate_scene_quality(self, scene):
+        """Validate that a scene contains meaningful content."""
+        try:
+            import numpy as np
+
+            scene_array = np.array(scene)
+
+            if len(scene_array.shape) == 3:  
+                variance = np.var(scene_array)
+                if variance < 10:  
+                    return False
+
+            if scene.width < 20 or scene.height < 20:
+                return False
+
+            return True
+
+        except Exception as e:
+            print(f"Scene quality check failed: {e}")
+            return True  
+    @log_execution
+    def analyze_comic_layout_with_enhanced_gemini(self, comic_image, num_scenes):
+        """
+        Enhanced Gemini Vision analysis with better prompting and fallback logic.
+        Specialized for detecting 12-panel layouts and complex grid structures.
+
+        Args:
+            comic_image: PIL.Image.Image object of the comic
+            num_scenes: Expected number of scenes (used for context and validation)
+
+        Returns:
+            tuple: (rows, cols) representing the detected grid layout
+        """
+        try:
+            model = GenerativeModel('gemini-2.5-flash')
+
+            buffered = io.BytesIO()
+            comic_image.save(buffered, format="PNG")
+            img_bytes = buffered.getvalue()
+
+            analysis_prompt = f"""
+            You are a professional comic book layout analyst. Examine this comic image carefully to determine its precise panel grid structure.
+
+            ANALYSIS TASK:
+            - Count the exact number of ROWS (horizontal divisions)
+            - Count the exact number of COLUMNS (vertical divisions)
+            - Expected panels: {num_scenes} (use as context, but trust what you see)
+
+            DETECTION GUIDELINES:
+            1. Look for panel borders, gutters, or visual separations
+            2. Identify consistent grid patterns
+            3. Count horizontal lines that divide rows
+            4. Count vertical lines that divide columns
+            5. For 12 panels, common layouts are: 3×4, 4×3, 2×6, or 6×2
+            6. Trust visual evidence over expected numbers
+
+            VISUAL INDICATORS TO LOOK FOR:
+            - Black border lines between panels
+            - White gutters or spacing between sections
+            - Consistent rectangular divisions
+            - Grid-like organization of content
+            - Clear separation of distinct visual areas
+
+            IMPORTANT: Be precise about what you actually observe. If you see a clear grid pattern, report it exactly.
+
+            Respond with ONLY this JSON format:
+            {{
+                "detected_rows": [number of rows you count],
+                "detected_cols": [number of columns you count],
+                "total_panels_detected": [rows × cols],
+                "confidence": "high/medium/low",
+                "layout_description": "detailed description of the grid structure you observe",
+                "visual_evidence": "description of the visual cues that led to this conclusion"
+            }}
+
+            Be extremely precise in your counting.
+            """
+
+            max_retries = 2
+            for attempt in range(max_retries):
+                try:
+                    response = model.generate_content([analysis_prompt, comic_image])
+                    response_text = response.text.strip()
+
+                    print(f"Gemini Vision analysis (attempt {attempt + 1}): {response_text[:200]}...")
+
+                    json_match = re.search(r'\{.*\}', response_text, re.DOTALL)
+                    if json_match:
+                        json_str = json_match.group()
+                        analysis_result = json.loads(json_str)
+
+                        rows = analysis_result.get("detected_rows", 0)
+                        cols = analysis_result.get("detected_cols", 0)
+                        total_detected = analysis_result.get("total_panels_detected", 0)
+                        confidence = analysis_result.get("confidence", "unknown")
+                        description = analysis_result.get("layout_description", "")
+                        evidence = analysis_result.get("visual_evidence", "")
+
+                        if rows > 0 and cols > 0:
+                            if total_detected == rows * cols:
+                                print(f"✅ Gemini detected {rows}×{cols} layout ({total_detected} panels) with {confidence} confidence")
+                                print(f"Evidence: {evidence}")
+
+                                if num_scenes == 12:
+                                    if total_detected in [10, 11, 12, 13, 14, 15, 16, 17, 18]:
+                                        print(f"📋 Layout reasonable for 12-panel comic")
+                                        return (rows, cols)
+                                    else:
+                                        print(f"⚠️ Detected {total_detected} panels for 12-panel comic. Using optimized layout.")
+                                        return self._calculate_optimal_grid_layout(num_scenes)
+                                else:
+                                    return (rows, cols)
+                            else:
+                                print(f"❌ Math inconsistency: {rows}×{cols} ≠ {total_detected}")
+                        else:
+                            print(f"❌ Invalid dimensions: {rows}×{cols}")
+
+                except json.JSONDecodeError as e:
+                    print(f"❌ JSON parsing error on attempt {attempt + 1}: {e}")
+                    if attempt == max_retries - 1:
+                        break
+
+                except Exception as e:
+                    print(f"❌ Analysis error on attempt {attempt + 1}: {e}")
+                    if attempt == max_retries - 1:
+                        break
+
+        except Exception as e:
+            print(f"❌ Gemini Vision analysis completely failed: {e}")
+
+        print("⚠️ Using optimized grid calculation as fallback")
+        return self._calculate_optimal_grid_layout(num_scenes)
+    @log_execution
+    def _find_all_factorizations(self, n):
+        """
+        Find all possible factorizations of a number into rows × columns.
+        Enhanced with better algorithm for large numbers like 24.
+
+        Args:
+            n: Number to factorize
+
+        Returns:
+            list: List of tuples (rows, cols) where rows * cols = n, sorted by preference
+        """
+        factorizations = []
+        for i in range(1, int(n**0.5) + 1):
+            if n % i == 0:
+                rows, cols = i, n // i
+                factorizations.append((rows, cols))
+                if rows != cols:
+                    factorizations.append((cols, rows))
+
+        factorizations.sort(key=lambda x: (abs(x[0] - x[1]), max(x[0], x[1])))
+        return factorizations
+    @log_execution
+    def _calculate_optimal_layout(self, num_scenes, image_width, image_height):
+        """
+        Calculate the optimal grid layout based on image aspect ratio and scene count.
+        Enhanced algorithm with better preferences for different panel counts.
+
+        Args:
+            num_scenes: Number of scenes to arrange
+            image_width: Width of the comic image
+            image_height: Height of the comic image
+
+        Returns:
+            tuple: (rows, cols) representing the optimal grid layout
+        """
+        image_aspect_ratio = image_width / image_height
+
+        factorizations = self._find_all_factorizations(num_scenes)
+
+        if not factorizations:
+            import math
+            sqrt_scenes = math.sqrt(num_scenes)
+            rows = int(sqrt_scenes)
+            cols = math.ceil(num_scenes / rows)
+            return (rows, cols)
+
+        best_layout = factorizations[0]
+        best_score = float('inf')
+
+        for rows, cols in factorizations:
+            layout_aspect_ratio = cols / rows
+
+            aspect_diff = abs(layout_aspect_ratio - image_aspect_ratio)
+
+            panel_aspect = (image_width / cols) / (image_height / rows)
+            extremeness_penalty = 0
+            if panel_aspect < 0.3 or panel_aspect > 3.0:
+                extremeness_penalty = 2.0
+
+            total_score = aspect_diff + extremeness_penalty
+
+            if total_score < best_score:
+                best_score = total_score
+                best_layout = (rows, cols)
+
+        return best_layout
+    @log_execution
+    def get_possible_layouts(self, num_scenes):
+        """
+        Get all possible layout options for a given number of scenes.
+        Enhanced with better layout suggestions.
+
+        Args:
+            num_scenes: Number of scenes
+
+        Returns:
+            list: List of tuples (rows, cols) representing possible layouts, sorted by preference
+        """
+        if num_scenes in [1, 2, 3, 4, 5, 6, 8, 9, 10, 12, 15, 16, 18, 20, 21, 24]:
+            optimal = self._calculate_optimal_grid_layout(num_scenes)
+            alternatives = self._find_all_factorizations(num_scenes)
+
+            layouts = [optimal]
+            layouts.extend([layout for layout in alternatives if layout != optimal])
+            return layouts
+        else:
+            return self._find_all_factorizations(num_scenes)
+    @log_execution
+    def generate_comic_with_quality_metrics(self, story_data, output_path=None, style=None):
+        """
+        Enhanced comic generation with quality metrics and validation.
+        Provides detailed feedback about the generation process.
+
+        Args:
+            story_data: Dictionary containing the story information
+            output_path: Optional path to save the resulting image
+            style: Optional comic style to use
+
+        Returns:
+            tuple: (comic_image, data_url, quality_metrics)
+        """
+        start_time = time.time()
+
+        title = story_data.get("title", "Enhanced Comic")
+        description = story_data.get("description", "")
+        characters = story_data.get("characters", [])
+        settings = story_data.get("settings", [])
+        num_scenes = 9 
+
+        quality_metrics = {
+            "character_count": len([c for c in characters if isinstance(c, dict) and "visual_description" in c]),
+            "setting_count": len([s for s in settings if isinstance(s, dict) and "description" in s]),
+            "description_length": len(description),
+            "optimal_layout": self._calculate_optimal_grid_layout(num_scenes),
+            "generation_complexity": "high" if num_scenes >= 20 else "medium" if num_scenes >= 10 else "low"
+        }
+
+        try:
+            prompt = self._create_comic_prompt(title, description, characters, settings, style, num_scenes)
+
+            print(f"🎨 Generating {num_scenes}-panel comic with enhanced prompt ({len(prompt)} characters)")
+
+            comic_image = generate_image_fn(
+                selected_prompt=prompt,
+                output_path=output_path
+            )
+
+            if comic_image is None:
+                comic_image = self._create_enhanced_placeholder_comic(title, description, num_scenes)
+                quality_metrics["generation_status"] = "placeholder"
+            else:
+                quality_metrics["generation_status"] = "success"
+
+            if output_path:
+                directory = os.path.dirname(output_path)
+                if directory and not os.path.exists(directory):
+                    os.makedirs(directory)
+                comic_image.save(output_path)
+
+            buffered = io.BytesIO()
+            comic_image.save(buffered, format="PNG")
+            img_bytes = buffered.getvalue()
+            img_b64 = base64.b64encode(img_bytes).decode("utf-8")
+            data_url = f"data:image/png;base64,{img_b64}"
+
+            end_time = time.time()
+            quality_metrics["generation_time"] = end_time - start_time
+            quality_metrics["image_size"] = (comic_image.width, comic_image.height)
+            quality_metrics["prompt_complexity"] = len(prompt.split())
+
+            return comic_image, data_url, quality_metrics
+
+        except Exception as e:
+            print(f"Error in enhanced generation: {str(e)}")
+            placeholder = self._create_enhanced_placeholder_comic(title, description, num_scenes)
+
+            buffered = io.BytesIO()
+            placeholder.save(buffered, format="PNG")
+            img_bytes = buffered.getvalue()
+            img_b64 = base64.b64encode(img_bytes).decode("utf-8")
+            data_url = f"data:image/png;base64,{img_b64}"
+
+            quality_metrics["generation_status"] = "error"
+            quality_metrics["error_message"] = str(e)
+
+            return placeholder, data_url, quality_metrics
+    @log_execution
+    def _create_enhanced_placeholder_comic(self, title, description, num_scenes):
+        """
+        Create an enhanced placeholder comic that shows the intended layout.
+
+        Args:
+            title: Title of the comic
+            description: Description of the comic
+            num_scenes: Number of scenes the comic should have
+
+        Returns:
+            PIL.Image.Image: Enhanced placeholder comic image
+        """
+        if num_scenes <= 4:
+            width, height = 800, 600
+        elif num_scenes <= 12:
+            width, height = 1200, 900
+        else:
+            width, height = 1600, 1200
+
+        comic = Image.new("RGB", (width, height), (248, 248, 248))
+        draw = ImageDraw.Draw(comic)
+
+        try:
+            title_font = ImageFont.truetype("Arial.ttf", max(24, width // 40))
+            panel_font = ImageFont.truetype("Arial.ttf", max(12, width // 80))
+            desc_font = ImageFont.truetype("Arial.ttf", max(10, width // 100))
+        except IOError:
+            title_font = panel_font = desc_font = ImageFont.load_default()
+
+        title_text = f"{title} - {num_scenes} Panel Layout Preview"
+        draw.text((20, 20), title_text, fill=(50, 50, 50), font=title_font)
+
+        layout = self._calculate_optimal_grid_layout(num_scenes)
+        rows, cols = layout
+
+        layout_info = f"Layout: {rows}×{cols} grid ({rows * cols} panels)"
+        draw.text((20, 60), layout_info, fill=(100, 100, 100), font=panel_font)
+
+        panel_area_y = 100
+        panel_area_height = height - panel_area_y - 60
+        panel_width = (width - 60) // cols
+        panel_height = panel_area_height // rows
+
+        panel_count = 0
+        for row in range(rows):
+            for col in range(cols):
+                if panel_count >= num_scenes:
+                    break
+
+                x = 30 + col * panel_width
+                y = panel_area_y + row * panel_height
+
+                draw.rectangle([x, y, x + panel_width - 10, y + panel_height - 10],
+                             outline=(150, 150, 150), fill=(255, 255, 255))
+
+                panel_text = f"Panel {panel_count + 1}"
+                draw.text((x + 10, y + 10), panel_text, fill=(100, 100, 100), font=panel_font)
+
+                panel_count += 1
+
+            if panel_count >= num_scenes:
+                break
+
+        if description and len(description) > 0:
+            desc_y = height - 50
+            wrapped_desc = textwrap.fill(description[:200] + "..." if len(description) > 200 else description, width=80)
+            draw.text((30, desc_y), wrapped_desc, fill=(80, 80, 80), font=desc_font)
+
+        return comic
+
+
+    @log_execution
+
+    def generate_panel_descriptions(self, final_prompt, num_scenes=9):
+        """
+        Generate panel-by-panel descriptions and format into complete comic generation prompt.
+        
+        Args:
+            final_prompt: The complete story/prompt text
+            num_scenes: Number of panels (default: 9)
+        
+        Returns:
+            str: Complete formatted prompt ready for image generation
+        """
+        try:
+            model = GenerativeModel('gemini-2.0-flash-exp')
+            
+            # First, generate the panel descriptions
+            analysis_prompt = f"""You are a master comic book storyteller. Break down this story into {num_scenes} COMPLETELY DIFFERENT panels.
+
+    STORY:
+    {final_prompt}
+
+    ABSOLUTE REQUIREMENTS FOR UNIQUENESS:
+
+    1. STORY STRUCTURE - Divide the story into {num_scenes} distinct narrative beats:
+    - Each panel = ONE specific story moment that happens at a DIFFERENT time
+    - Panel 1 happens BEFORE Panel 2, Panel 2 BEFORE Panel 3, etc.
+    - NO panel should show the same moment or similar action
+    - Think of it like a movie: each panel is a different scene
+
+    2. VISUAL VARIETY - Each panel MUST have:
+    - DIFFERENT location or setting (if story allows)
+    - DIFFERENT character positions and poses
+    - DIFFERENT camera angle/shot type
+    - DIFFERENT action or emotional beat
+    - DIFFERENT time of day or lighting (if applicable)
+
+    3. SHOT TYPES - Use variety:
+    - Extreme Wide Shot, Wide Shot, Medium Shot, Close-Up, Extreme Close-Up, Over-the-Shoulder, Low Angle, High Angle, Bird's Eye View
+
+    FORMAT EXACTLY LIKE THIS:
+    Panel 1: [Title]
+    Shot Type: [Type]
+    Content: [Detailed description]
+
+    Panel 2: [Different title]
+    Shot Type: [Different type]
+    Content: [Completely different scene]
+
+    Generate all {num_scenes} panels now:"""
+
+            generation_config = GenerationConfig(
+                temperature=0.9,
+                top_p=0.95,
+            )
+            
+            response = model.generate_content(analysis_prompt, generation_config=generation_config)
+            panel_descriptions = response.text.strip()
+            
+            # Now format into the complete prompt structure
+            grid_layout = "3x3 grid (3 rows, 3 columns)" if num_scenes == 9 else f"{num_scenes} panels"
+            
+            complete_prompt = f'''"""CRITICAL COMMAND: UNIFORM {grid_layout.upper()} (NON-NEGOTIABLE)
+
+    Layout: Generate exactly {num_scenes} panels in a {grid_layout}.
+    Panel Integrity: Every panel MUST be identical in size and shape. Do not change panel dimensions for any reason.
+    Formatting: Use clean, equal-width white gutters between all panels and a uniform thin black border around each panel.
+    CRITICAL RULE: SILENT COMIC - NO TEXT, NO SPEECH BUBBLES, NO SOUND EFFECTS, NO CAPTIONS EVER.
+    CRITICAL RULE: EACH PANEL IS A DISTINCT SCENE.
+    Each panel must depict a unique, self-contained moment or tableau from the story.
+    PANEL-BY-PANEL STORYBOARD (READ LEFT-TO-RIGHT, TOP-TO-BOTTOM)
+    {panel_descriptions}
+
+    GLOBAL STYLE & CONSISTENCY MANDATES
+    Art Style: Modern Digital Manga
+
+    Line Art: Sharp digital lines, clean and precise, emphasizing dynamic movement and emotional clarity.
+    Tones & Shading: Cel shading with clear, distinct shadows and highlights, giving a vibrant yet defined look.
+    Composition: Every panel must have a clear focal point and excellent use of foreground, midground, and background elements.
+    Character Consistency: Characters must maintain consistent facial features, hair, and design throughout all panels while showing progression in age, clothing, or emotional state as the story requires.
+    Environmental & Lighting Continuity: Lighting and atmosphere should support the narrative progression and emotional tone of each scene.
+    Color Palette: A vibrant and saturated palette that enhances the story's emotional journey.
+
+    FINAL OVERRIDE & NEGATIVE PROMPTS
+    ABSOLUTE RULE: The {grid_layout} uniform grid structure is the most important rule and must be followed perfectly.
+    NEGATIVE PROMPTS: NO deformed anatomy, NO missing limbs or facial features, NO inconsistent character designs, NO blurry or out-of-focus elements, NO sketch-like aesthetics (unless intentional style choice), NO TEXT, NO SPEECH BUBBLES, NO SOUND EFFECTS, NO CAPTIONS, NO watermarks, NO VARIATION IN PANEL SIZE OR SHAPE.
+    """'''
+            
+            print(f"Generated complete prompt with {num_scenes} panels")
+            
+            return complete_prompt
+                
+        except Exception as e:
+            print(f"Error generating complete prompt: {e}")
+            return None

models/image_generation.py

@@ -0,0 +1,264 @@
+import io
+import base64
+import os
+from PIL import Image
+import config
+from openai import OpenAI
+import warnings
+import time
+from google.generativeai import GenerativeModel
+from datetime import datetime
+warnings.filterwarnings("ignore", message="IMAGE_SAFETY is not a valid FinishReason")
+
+global_image_data_url = None
+global_image_prompt = None
+global_image_description = None
+
+def log_execution(func):
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        start_str = datetime.fromtimestamp(start_time).strftime('%Y-%m-%d %H:%M:%S')
+        
+        result = func(*args, **kwargs)
+        
+        end_time = time.time()
+        end_str = datetime.fromtimestamp(end_time).strftime('%Y-%m-%d %H:%M:%S')
+        duration = end_time - start_time
+        
+        # Write to file (works in Colab)
+        with open('content/logs.txt', 'a') as f:
+            f.write(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s\n")
+        
+        # Also print to see output immediately
+        print(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s")
+        
+        return result
+    return wrapper
+
+@log_execution
+def generate_image_fn_deprecated (selected_prompt, model="gpt-image-1", output_path="models\benchmark"):
+    """
+    Generate an image from the prompt via the OpenAI API using gpt-image-1.
+    Convert the image to a data URL and optionally save it to a file.
+
+    Args:
+        selected_prompt (str): The prompt to generate the image from.
+        model (str): Should be "gpt-image-1". Parameter kept for compatibility.
+        output_path (str, optional): If provided, saves the image to this path. Defaults to None.
+
+    Returns:
+        PIL.Image.Image or None: The generated image as a PIL Image object, or None on error.
+    """
+    global global_image_data_url, global_image_prompt
+    
+    MAX_PROMPT_LENGTH = 32000
+    if len(selected_prompt) > MAX_PROMPT_LENGTH:
+        selected_prompt = smart_truncate_prompt(selected_prompt, MAX_PROMPT_LENGTH)
+        print(f"Warning: Prompt was smartly truncated to {len(selected_prompt)} characters while preserving critical details")
+    
+    global_image_prompt = selected_prompt
+
+    model = "gpt-image-1"
+
+    try:
+        client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY", config.OPENAI_API_KEY))
+
+        api_params = {
+            "model": model,
+            "prompt": selected_prompt,
+            "size": "1024x1536" ,
+            "quality": "high",
+            "moderation":"low"
+        }
+
+        result = client.images.generate(**api_params)
+
+        
+
+        image_bytes = base64.b64decode(image_base64)
+
+        image = Image.open(io.BytesIO(image_bytes))
+
+        if output_path:
+            try:
+                os.makedirs(os.path.dirname(output_path), exist_ok=True)
+                with open(output_path, "wb") as f:
+                    f.write(image_bytes)
+                print(f"Successfully saved image to {output_path}")
+            except Exception as e:
+                print(f"Error saving image to {output_path}: {str(e)}")
+
+        buffered = io.BytesIO()
+        image.save(buffered, format="PNG")
+        img_bytes = buffered.getvalue()
+        img_b64 = base64.b64encode(img_bytes).decode("utf-8")
+        global_image_data_url = f"data:image/png;base64,{img_b64}"
+
+        print(f"Successfully generated image with prompt: {selected_prompt[:50]}...")
+        return image  
+    except Exception as e:
+        print(f"Error generating image: {str(e)}")
+        return None 
+@log_execution
+def generate_image_fn(selected_prompt, model="gemini-2.5-flash-image-preview", output_path="models/benchmark"):
+    """
+    Generate an image from the prompt via the Google Gemini API using vertexai.
+    Convert the image to a data URL and optionally save it to a file.
+
+    Args:
+        selected_prompt (str): The prompt to generate the image from.
+        model (str): The Gemini model to use. Defaults to "gemini-2.5-flash-image-preview".
+        output_path (str, optional): If provided, saves the image to this path. Defaults to "models/benchmark".
+
+    Returns:
+        PIL.Image.Image or None: The generated image as a PIL Image object, or None on error.
+    """
+    global global_image_data_url, global_image_prompt
+    
+    MAX_PROMPT_LENGTH = 32000
+    if len(selected_prompt) > MAX_PROMPT_LENGTH:
+        selected_prompt = smart_truncate_prompt(selected_prompt, MAX_PROMPT_LENGTH)
+        print(f"Warning: Prompt was smartly truncated to {len(selected_prompt)} characters while preserving critical details")
+    
+    global_image_prompt = selected_prompt
+
+    try:
+        from google.generativeai import GenerativeModel
+        from PIL import Image
+        import io
+        import base64
+        import os
+        
+        # Initialize the Gemini model
+        gemini_model = GenerativeModel(model)
+        
+        # Generate content with the prompt
+        response = gemini_model.generate_content([selected_prompt])
+        
+        # Extract the generated image from the response
+        image = None
+        image_bytes = None
+        has_text_response = False
+        
+        for part in response.candidates[0].content.parts:
+            # Check for text responses (ignore these)
+            if hasattr(part, 'text') and part.text:
+                has_text_response = True
+                print(f"Ignoring text response from API: {part.text[:100]}...")
+                continue
+            
+            # Look for image data
+            if hasattr(part, 'inline_data') and part.inline_data is not None:
+                image_bytes = part.inline_data.data
+                
+                # Verify we have valid data
+                if not image_bytes or len(image_bytes) == 0:
+                    print("Warning: inline_data.data is empty, skipping...")
+                    continue
+                
+                # Try to parse the image
+                try:
+                    img_io = io.BytesIO(image_bytes)
+                    image = Image.open(img_io)
+                    image.load()  # Force load to verify it's valid
+                    print(f"Successfully loaded image: {len(image_bytes)} bytes")
+                    break
+                except Exception as img_error:
+                    print(f"Invalid image data received, skipping: {img_error}")
+                    continue
+        
+        # If we only got text and no image, return None
+        if image is None:
+            if has_text_response:
+                print("API returned text instead of image - skipping this response")
+            else:
+                print("No image data found in response")
+            return None
+        
+        # Save image to file if output_path is provided
+        if output_path:
+            try:
+                os.makedirs(os.path.dirname(output_path), exist_ok=True)
+                # Ensure output_path has an image extension
+                if not output_path.lower().endswith(('.png', '.jpg', '.jpeg')):
+                    output_path = f"{output_path}.png"
+                
+                image.save(output_path)
+                print(f"Successfully saved image to {output_path}")
+            except Exception as e:
+                print(f"Error saving image to {output_path}: {str(e)}")
+        
+        # Create data URL for the image
+        buffered = io.BytesIO()
+        image.save(buffered, format="PNG")
+        img_bytes = buffered.getvalue()
+        img_b64 = base64.b64encode(img_bytes).decode("utf-8")
+        global_image_data_url = f"data:image/png;base64,{img_b64}"
+        
+        print(f"Successfully generated image with prompt: {selected_prompt[:50]}...")
+        return image
+    
+    except Exception as e:
+        print(f"Error generating image: {str(e)}")
+        import traceback
+        traceback.print_exc()
+        return None
+    
+
+@log_execution
+def smart_truncate_prompt(prompt, max_length):
+    """
+    Smart truncation that preserves critical details and visual consistency information.
+    Prioritizes character descriptions, layout specifications, and technical requirements.
+    """
+    if len(prompt) <= max_length:
+        return prompt
+    
+    critical_sections = [
+        "CRITICAL LAYOUT:",
+        "🎭 CRITICAL CHARACTER CONSISTENCY PROTOCOL:",
+        "CHARACTER 1",
+        "CHARACTER 2", 
+        "CHARACTER 3",
+        "STORY CONTENT:",
+        "🏗️ ENVIRONMENTAL CONSISTENCY PROTOCOL:",
+        "🎨 COMIC BOOK STYLE MASTERY:",
+        "🎨 AUTHENTIC MANGA STYLE:",
+        "🎨 PHOTOREALISTIC EXCELLENCE:",
+        "🎨 CINEMATIC VISUAL MASTERY:",
+        "🎨 HIGH-QUALITY ILLUSTRATION:",
+        "📐 PANEL COMPOSITION MASTERY:",
+        "🔍 DETAIL PRESERVATION PROTOCOL:",
+        "⚡ ADVANCED QUALITY REQUIREMENTS:"
+    ]
+    
+    sections = prompt.split(" || ")
+    
+    preserved_sections = []
+    preserved_length = 0
+    
+    for section in sections:
+        section_trimmed = section.strip()
+        if not section_trimmed:
+            continue
+            
+        is_critical = any(critical_marker in section_trimmed for critical_marker in critical_sections[:8])  
+        
+        if is_critical or (preserved_length + len(section_trimmed) + 4 < max_length - 200):  
+            preserved_sections.append(section_trimmed)
+            preserved_length += len(section_trimmed) + 4  
+        elif preserved_length < max_length * 0.7:  
+            available_space = max_length - preserved_length - 200
+            if available_space > 100:  
+                truncated_section = section_trimmed[:available_space-20] + "..."
+                preserved_sections.append(truncated_section)
+                break
+    
+    preserved_prompt = " || ".join(preserved_sections)
+    
+    final_mandate = " || FINAL MANDATE: Create a masterpiece with perfect character consistency and narrative clarity"
+    if len(preserved_prompt) + len(final_mandate) <= max_length:
+        preserved_prompt += final_mandate
+    
+    return preserved_prompt
+

models/story_generator.py

@@ -0,0 +1,562 @@
+from google.generativeai import GenerativeModel
+import json
+import re
+import os
+import datetime
+import openai
+import config
+import time
+from datetime import datetime
+
+
+def log_execution(func):
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        start_str = datetime.fromtimestamp(start_time).strftime('%Y-%m-%d %H:%M:%S')
+        
+        result = func(*args, **kwargs)
+        
+        end_time = time.time()
+        end_str = datetime.fromtimestamp(end_time).strftime('%Y-%m-%d %H:%M:%S')
+        duration = end_time - start_time
+        
+        # Write to file (works in Colab)
+        with open('content/logs.txt', 'a') as f:
+            f.write(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s\n")
+        
+        # Also print to see output immediately
+        print(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s")
+        
+        return result
+    return wrapper
+
+class StoryGenerator:
+    """
+    Direct story generator that creates comic panel style stories from user input.
+    """
+
+    def __init__(self):
+        self.model = GenerativeModel('gemini-2.5-flash')
+    @log_execution
+    def log_prompt(self, prompt, log_file="story_prompt_logs.jsonl"):
+        """Log the prompt to a file for debugging and improvement purposes."""
+        log_entry = {
+            "timestamp": datetime.datetime.now().isoformat(),
+            "prompt": prompt
+        }
+        with open(log_file, "a", encoding="utf-8") as f:
+            f.write(json.dumps(log_entry, ensure_ascii=False) + "\n")
+    @log_execution
+    def enhance_user_story(self, user_description, max_retries=3, current_retry=0):
+        """
+        Enhance the user's story with more vibrancy, detail, and narrative richness using
+        optimized AI prompting techniques for visual storytelling with smart detail preservation.
+        
+        Args:
+            user_description: The user's original story idea or prompt
+            max_retries: Maximum number of retry attempts (default: 3)
+            current_retry: Current retry attempt number (default: 0)
+            
+        Returns:
+            enhanced_story: A more vibrant and detailed version of the story with preserved key elements
+        """
+        print(f"[StoryGenerator] Enhancing user story (attempt {current_retry + 1}/{max_retries}): {user_description[:100]}...")
+        
+        if current_retry >= max_retries:
+            print(f"[StoryGenerator] Max retries reached, returning original description")
+            return user_description
+        
+        try:
+            enhancement_prompt = self._create_detail_focused_enhancement_prompt(user_description)
+            
+            self.log_prompt(enhancement_prompt)
+            
+            try:
+                response = self.model.generate_content(enhancement_prompt)
+                enhanced_story = response.text.strip()
+                
+                if self._validate_enhancement_quality(enhanced_story, user_description):
+                    print(f"[StoryGenerator] Story successfully enhanced with detail preservation")
+                    return enhanced_story
+                else:
+                    print(f"[StoryGenerator] Enhancement quality insufficient, using original with minimal enhancement")
+                    return self._create_minimal_enhancement(user_description)
+                
+            except Exception as gemini_error:
+                print(f"[StoryGenerator] Gemini API error: {gemini_error}")
+                if current_retry < max_retries - 1:
+                    print(f"[StoryGenerator] Retrying with simplified approach...")
+                    return self._simplified_enhancement(user_description)
+                else:
+                    raise gemini_error
+                    
+        except Exception as e:
+            print(f"[StoryGenerator] Enhancement error: {e}")
+            if current_retry < max_retries - 1:
+                import time
+                time.sleep(1 * (current_retry + 1))  
+                return self.enhance_user_story(user_description, max_retries, current_retry + 1)
+            else:
+                print(f"[StoryGenerator] All enhancement attempts failed, returning original")
+                return user_description
+    @log_execution
+
+    def _create_detail_focused_enhancement_prompt(self, user_description):
+        """Create a concise enhancement prompt that adds coherence and enough detail for the required number of scenes."""
+        return f"""
+        You are an expert visual storytelling assistant. Enhance the user's story concept to create a rich visual narrative.
+
+        ORIGINAL STORY: "{user_description}"
+
+        ENHANCEMENT GOALS:
+        •   Define key character appearances (visual features, clothing).
+        •   Establish a clear setting and atmosphere.
+        •   Outline a logical scene progression that can be broken down into multiple action-focused panels.
+        •   Ensure visual consistency for characters and locations.
+        •   Descriptions should be concise yet vivid, focusing on elements crucial for an action-oriented digital comic.
+
+        OUTPUT: Enhanced story description (2-3 paragraphs maximum) that provides a strong foundation for a multi-panel, action-focused visual story. Ensure the tone is suitable for a modern digital comic.
+        """
+
+    def _validate_enhancement_quality(self, enhanced_story, original_story):
+        """Validate that the enhancement adds coherence and appropriate detail."""
+        if not enhanced_story or len(enhanced_story) < 50:
+            return False
+        
+        enhanced_words = len(enhanced_story.split())
+        original_words = len(original_story.split())
+        
+        if enhanced_words < original_words or enhanced_words > original_words * 5:
+            return False
+        
+        story_elements = ['character', 'scene', 'story', 'visual', 'setting', 'action']
+        has_story_elements = sum(1 for element in story_elements if element.lower() in enhanced_story.lower())
+        
+        if has_story_elements < 2:
+            return False
+        
+        similarity_threshold = 0.8
+        original_lower = original_story.lower()
+        enhanced_lower = enhanced_story.lower()
+        
+        common_words = set(original_lower.split()) & set(enhanced_lower.split())
+        original_unique = len(set(original_lower.split()))
+        
+        if original_unique > 0:
+            similarity = len(common_words) / original_unique
+            if similarity > similarity_threshold and enhanced_words < original_words * 1.5:
+                return False
+        
+        return True
+    @log_execution
+
+    def _create_minimal_enhancement(self, user_description):
+        """Create minimal enhancement that preserves original while adding basic coherence for the required number of scenes."""
+        
+        enhanced = f"""
+        Enhanced Story: {user_description}
+        
+        Visual Coherence Elements:
+        - Main character with consistent appearance throughout all scenes
+        - Clear setting that remains visually consistent
+        - Logical progression suitable for the required number of sequential panels
+        - Simple but complete story arc with beginning, middle, and end
+        
+        This story will unfold across the required number of scenes showing the character's journey with visual consistency and narrative coherence.
+        """
+        
+        return enhanced.strip()
+    @log_execution
+
+    def _simplified_enhancement(self, user_description):
+        """
+        Simplified enhancement fallback when the main enhancement fails.
+        
+        Args:
+            user_description: Original user story description
+            
+        Returns:
+            str: Simplified enhanced description focused on coherence for the required number of scenes.
+        """
+        try:
+            simplified_prompt = f"""
+            Briefly enhance this story for an action-focused visual narrative. Keep it concise and coherent.
+
+            Original: "{user_description}"
+
+            Focus on:
+            - Core character appearance notes.
+            - Main setting description.
+            - Basic story flow suitable for action scenes.
+            - Visual consistency hints.
+
+            Enhanced story (1-2 sentences):
+            """
+            
+            response = self.model.generate_content(simplified_prompt)
+            enhanced_story = response.text.strip()
+            
+            if enhanced_story and len(enhanced_story) > 20:
+                print(f"[StoryGenerator] Used simplified enhancement successfully")
+                return enhanced_story
+            else:
+                return user_description
+                
+        except Exception as e:
+            print(f"[StoryGenerator] Simplified enhancement also failed: {e}")
+            return user_description
+    @log_execution
+    def generate_story(self, user_description, panels_per_page=9, num_pages=1):
+        """
+        Generate a comic panel style story directly from user input.
+        
+        Args:
+            user_description: The user's story idea or prompt
+            panels_per_page: Number of panels per comic page (default is 8)
+            num_pages: Number of pages to generate (default is 1)
+            
+        Returns:
+            story_data: Structured data for the story with panels organized by pages
+        """
+        enhanced_story = self.enhance_user_story(user_description)
+
+        panels_per_page = 9
+        total_panels = panels_per_page * num_pages
+        print(f"[StoryGenerator] Generating comic story with {num_pages} pages, {panels_per_page} panels per page ({total_panels} total panels) from enhanced story...")
+        
+        query = f"""
+        You are a world-class comic book writer and visual storyteller. Your task is to create a SINGLE CONTINUOUS STORY.
+        The story will span exactly {num_pages} pages. Each page must contain exactly {panels_per_page} sequential action-focused panels (total of {total_panels} panels).
+        The final output must be a modern, digital-style comic with high quality and resolution, suitable for a 1024x1536 image size. **All {panels_per_page} panels must fit entirely within the page with clear gutters—no panel content may be cropped or cut off.**
+        Avoid any deformities, missing limbs, distorted or missing facial features, blurry visuals, or sketch styles. Ensure all panels are exactly the same size.
+
+        STORY CONCEPT:
+        "{enhanced_story}"
+
+        KEY REQUIREMENTS:
+        1.  **Panel Count & Style**: Strictly {panels_per_page} action scenes per page. No filler. All scenes must be dynamic and contribute to the story's momentum.
+        2.  **Visual Quality**: Generate ultra-high quality, modern digital comic art. Ensure no visual defects (deformities, missing limbs, distorted faces). All panels must be suitable for a combined 1024x1536 page layout.
+        3.  **Continuity**:
+            *   Story must flow seamlessly page-to-page and panel-to-panel.
+            *   Maintain consistent character appearances (detailed in a character sheet you will generate) and settings (detailed in a setting guide you will generate).
+            *   Logical plot progression: actions have clear causes and effects.
+            *   Show passage of time clearly (e.g., "later," "next day").
+        4.  **Narrative Structure**:
+            *   Complete arc: beginning, rising action, climax, resolution.
+            *   Meaningful character development and motivations.
+        5.  **Visual Storytelling Focus**:
+            *   Descriptions should emphasize actions, expressions, and settings to make the story understandable through visuals alone.
+            *   Each panel description needs: camera angle, character positions, expressions, environment details, color palette, and mood.
+            *   Focus on clear, dynamic action sequences.
+
+        JSON OUTPUT STRUCTURE:
+        {{
+          "title": "Overall Story Title",
+          "premise": "Brief story overview, themes, and setting.",
+          "characters": [
+            {{
+              "name": "Character Name",
+              "visual_description": "DETAILED visual description: height, build, face, hair, clothing. CRITICAL for consistency.",
+              "traits": ["Key visual trait 1", "Key visual trait 2"],
+              "background": "Brief backstory.",
+              "arc": "Character's journey/change."
+            }}
+            // ... (add more characters as needed)
+          ],
+          "settings": [
+            {{
+              "name": "Setting Name",
+              "description": "DETAILED visual description of the location, including key elements for consistency.",
+              "visual_elements": ["Notable visual element 1", "Notable visual trait 2"],
+              "mood": "Atmosphere of the location."
+            }}
+            // ... (add more settings as needed)
+          ],
+          "pages": [
+            {{
+              "page_number": 1,
+              "panels": [ // Exactly {panels_per_page} panels
+                {{
+                  "panel_number": 1,
+                  "title": "Action-Oriented Panel Title",
+                  "visual_description": "ACTION-FOCUSED, extremely detailed description: character actions, expressions, positions, environment, lighting, colors, camera angle. Ensure it fits 1024x1536 page context. NO FILLER.",
+                  "text": "Dialogue/narration (context only, not for image)",
+                  "purpose": "How this ACTION panel drives the story.",
+                  "symbolism": "Any visual symbols."
+                }}
+                // ... (repeat for all {panels_per_page} panels on page 1)
+              ]
+            }}
+            // ... (repeat for all {num_pages} pages)
+          ]
+        }}
+
+        REMEMBER:
+        - Focus on ACTION scenes. Eliminate all filler.
+        - Visuals are paramount. Descriptions must be rich and allow for image generation that tells the story without text.
+        - Adhere strictly to {panels_per_page} panels per page.
+        - Ensure top-tier digital art quality with no visual errors.
+        - All panels on a page contribute to a single 1024x1536 image.
+        """
+        
+        self.log_prompt(query)
+        response = self.model.generate_content(query)
+        
+        try:
+            json_match = re.search(r'\{[\s\S]*\}', response.text, re.DOTALL)
+            if json_match:
+                json_str = json_match.group(0)
+                
+                json_str = self._fix_json(json_str)
+                
+                story_data = json.loads(json_str)
+                
+                story_data = self._validate_and_fix_structure(story_data, panels_per_page, num_pages)
+                
+                print(f"[StoryGenerator] Successfully generated story: {story_data.get('title', 'Untitled')}")
+                return story_data
+            else:
+                print("[StoryGenerator] No valid JSON found in response.")
+                raise ValueError("No valid JSON found in response")
+        except Exception as e:
+            print(f"Error in StoryGenerator: {e}")
+            return self._create_fallback_story(user_description, panels_per_page, num_pages)
+    @log_execution
+    def _validate_and_fix_structure(self, story_data, panels_per_page, num_pages):
+        """Validate and fix the story structure if needed."""
+        if "title" not in story_data:
+            story_data["title"] = "Untitled Comic"
+            
+        if "premise" not in story_data:
+            story_data["premise"] = "A visual story."
+            
+        if "characters" not in story_data:
+            story_data["characters"] = []
+        
+        for character in story_data.get("characters", []):
+            if "visual_description" not in character:
+                character["visual_description"] = "A character in the story."
+            if "traits" not in character:
+                character["traits"] = []
+            if "background" not in character:
+                character["background"] = "Unknown background."
+            if "arc" not in character:
+                character["arc"] = "Experiences events throughout the story."
+            
+        if "settings" not in story_data:
+            story_data["settings"] = []
+            
+        for setting in story_data.get("settings", []):
+            if "description" not in setting:
+                setting["description"] = "A location in the story."
+            if "visual_elements" not in setting:
+                setting["visual_elements"] = []
+            if "mood" not in setting:
+                setting["mood"] = "Neutral."
+            
+        if "pages" not in story_data:
+            if "panels" in story_data:
+                panels = story_data.pop("panels")
+                story_data["pages"] = []
+                
+                for i in range(num_pages):
+                    start_idx = i * panels_per_page
+                    end_idx = start_idx + panels_per_page
+                    page_panels = panels[start_idx:end_idx] if start_idx < len(panels) else []
+                    
+                    while len(page_panels) < panels_per_page:
+                        panel_num = len(page_panels) + 1 + (i * panels_per_page)
+                        page_panels.append({
+                            "panel_number": panel_num,
+                            "title": f"Panel {panel_num}",
+                            "visual_description": "A placeholder panel",
+                            "text": "",
+                            "purpose": "Continuation of the story",
+                            "symbolism": ""
+                        })
+                    
+                    story_data["pages"].append({
+                        "page_number": i + 1,
+                        "panels": page_panels
+                    })
+            else:
+                story_data["pages"] = []
+                for i in range(num_pages):
+                    page_panels = []
+                    for j in range(panels_per_page):
+                        panel_num = j + 1 + (i * panels_per_page)
+                        page_panels.append({
+                            "panel_number": panel_num,
+                            "title": f"Panel {panel_num}",
+                            "visual_description": "A placeholder panel",
+                            "text": "",
+                            "purpose": "Continuation of the story",
+                            "symbolism": ""
+                        })
+                    
+                    story_data["pages"].append({
+                        "page_number": i + 1,
+                        "panels": page_panels
+                    })
+        
+        for i in range(len(story_data["pages"]) - 1):
+            current_page = story_data["pages"][i]
+            next_page = story_data["pages"][i + 1]
+            
+            if "panels" in current_page and "panels" in next_page and current_page["panels"] and next_page["panels"]:
+                last_panel = current_page["panels"][-1]
+                first_panel = next_page["panels"][0]
+                
+                last_panel_desc = last_panel.get("visual_description", "")
+                last_panel_action = last_panel.get("text", "")
+                
+                continuity_note = f"Continues directly from page {current_page.get('page_number', i+1)}, panel {last_panel.get('panel_number', len(current_page['panels']))}: {last_panel_desc[:100]}..."
+                
+                first_panel["continuity_note"] = continuity_note
+                
+                if "visual_description" in first_panel:
+                    if not first_panel["visual_description"].startswith("CONTINUING DIRECTLY"):
+                        first_panel["visual_description"] = "CONTINUING DIRECTLY from previous page: " + first_panel["visual_description"]
+        
+        for i, page in enumerate(story_data["pages"]):
+            if "page_number" not in page:
+                page["page_number"] = i + 1
+                
+            if "panels" not in page:
+                page["panels"] = []
+                
+            if len(page["panels"]) > panels_per_page:
+                page["panels"] = page["panels"][:panels_per_page]
+            
+            while len(page["panels"]) < panels_per_page:
+                panel_num = len(page["panels"]) + 1 + (i * panels_per_page)
+                
+                context_desc = ""
+                if page["panels"]:
+                    prev_panel = page["panels"][-1]
+                    prev_desc = prev_panel.get("visual_description", "")
+                    context_desc = f"Continuing from previous panel: {prev_desc[:50]}... "
+                
+                page["panels"].append({
+                    "panel_number": panel_num,
+                    "title": f"Panel {panel_num}",
+                    "visual_description": f"{context_desc}A scene related to the story, moving the narrative forward.",
+                    "text": "",
+                    "purpose": "Continuation of the story progression",
+                    "symbolism": ""
+                })
+            
+            for j, panel in enumerate(page["panels"]):
+                panel_num = j + 1 + (i * panels_per_page)
+                
+                if "panel_number" not in panel:
+                    panel["panel_number"] = panel_num
+                
+                if "title" not in panel or not panel["title"]:
+                    panel["title"] = f"Panel {panel_num}"
+                
+                if "visual_description" not in panel or not panel["visual_description"]:
+                    context_desc = ""
+                    if j > 0:
+                        prev_panel = page["panels"][j-1]
+                        prev_desc = prev_panel.get("visual_description", "")
+                        context_desc = f"Following from previous panel: {prev_desc[:50]}... "
+                    
+                    panel["visual_description"] = f"{context_desc}A scene that advances the story narrative."
+                
+                if "text" not in panel:
+                    panel["text"] = ""
+                
+                if "purpose" not in panel:
+                    panel["purpose"] = "Advancing the story progression"
+                
+                if "symbolism" not in panel:
+                    panel["symbolism"] = ""
+        
+        while len(story_data["pages"]) < num_pages:
+            page_num = len(story_data["pages"]) + 1
+            page_panels = []
+            
+            context_from_prev_page = ""
+            if story_data["pages"]:
+                prev_page = story_data["pages"][-1]
+                if prev_page.get("panels"):
+                    last_panel = prev_page["panels"][-1]
+                    last_desc = last_panel.get("visual_description", "")
+                    context_from_prev_page = f"Continuing directly from the previous page: {last_desc[:100]}... "
+            
+            for j in range(panels_per_page):
+                panel_num = j + 1 + ((page_num - 1) * panels_per_page)
+                
+                panel_desc = "A scene that advances the story narrative."
+                if j == 0 and context_from_prev_page:
+                    panel_desc = context_from_prev_page + panel_desc
+                elif j > 0 and page_panels:
+                    prev_panel = page_panels[j-1]
+                    prev_desc = prev_panel.get("visual_description", "")
+                    panel_desc = f"Following from previous panel: {prev_desc[:50]}... " + panel_desc
+                
+                page_panels.append({
+                    "panel_number": panel_num,
+                    "title": f"Panel {panel_num}",
+                    "visual_description": panel_desc,
+                    "text": "",
+                    "purpose": "Advancing the story progression",
+                    "symbolism": ""
+                })
+            
+            story_data["pages"].append({
+                "page_number": page_num,
+                "panels": page_panels
+            })
+            
+        return story_data
+    @log_execution
+    def _create_fallback_story(self, user_description, panels_per_page, num_pages):
+        """Create a basic fallback story structure if generation fails."""
+        pages = []
+        
+        for i in range(num_pages):
+            page_panels = []
+            for j in range(panels_per_page):
+                panel_num = j + 1 + (i * panels_per_page)
+                page_panels.append({
+                    "panel_number": panel_num,
+                    "title": f"Panel {panel_num}",
+                    "visual_description": f"A scene related to {user_description[:30]}...",
+                    "text": f"Text for panel {panel_num}",
+                    "purpose": f"Part of the story progression",
+                    "symbolism": ""
+                })
+            
+            pages.append({
+                "page_number": i + 1,
+                "panels": page_panels
+            })
+        
+        return {
+            "title": f"A Story About {user_description[:30]}...",
+            "premise": f"A comic story about {user_description[:50]}...",
+            "pages": pages
+        }
+    @log_execution
+
+    def _fix_json(self, json_str):
+        """Attempt to fix common JSON issues from LLM responses."""
+        json_str = re.sub(r'//.*?', '', json_str)
+        json_str = re.sub(r'/\*[\s\S]*?\*/', '', json_str, flags=re.DOTALL)
+
+        json_str = re.sub(r'([{, ]\s*)([a-zA-Z_][a-zA-Z0-9_]*)(\s*:)', r'\1"\2"\3', json_str)
+
+        json_str = re.sub(r',(\s*[}\\]])', r'\1', json_str)
+        return json_str
+    @log_execution
+
+    def generate_panel_image_prompt(self, panel_data, style=None):
+        """Generate a prompt for image generation from panel data."""
+        style_text = f" in {style} style" if style else ""
+        
+        prompt = f"Create a comic book panel{style_text} showing: {panel_data['visual_description']}. "
+        if 'text' in panel_data and panel_data['text']:
+            prompt += f"The panel includes the dialogue: '{panel_data['text']}'. "
+        return prompt 

new_image_splitting.py

@@ -0,0 +1,278 @@
+import cv2
+import numpy as np
+import os
+from pathlib import Path
+from PIL import Image
+
+class AutomatedCollageSplitter:
+    def __init__(self):
+        self.min_segment_area_ratio = 0.01
+        self.max_segment_area_ratio = 0.95
+        self.min_aspect_ratio = 0.2
+        self.max_aspect_ratio = 5.0
+        self.min_solidity = 0.9
+        self.nms_threshold = 0.3
+
+        self.upscaler = None
+        self._initialize_upscaler()
+
+    def _initialize_upscaler(self):
+        if self.upscaler is not None:
+            return
+        try:
+            model_name = 'fsrcnn'
+            model_path = os.path.join('models', 'weights', 'FSRCNN-small_x4.pb')
+            scale = 4
+            if not os.path.isfile(model_path):
+                raise FileNotFoundError(f"Model file not found at {model_path}")
+            self.upscaler = cv2.dnn_superres.DnnSuperResImpl_create()
+            self.upscaler.readModel(model_path)
+            self.upscaler.setModel(model_name, scale)
+            print(f"✓ OpenCV DNN upscaler model loaded: {model_name} with scale x{scale}")
+        except Exception as e:
+            print(f"⚠ Could not initialize OpenCV DNN upscaler: {e}. Proceeding without upscaling.")
+            self.upscaler = None
+
+    def _upscale_image(self, image_array):
+        if not self.upscaler:
+            print("❌ Upscaling skipped because the upscaler is not available.")
+            return image_array
+        try:
+            return self.upscaler.upsample(image_array)
+        except Exception as e:
+            print(f"❌ Error during image upscaling: {e}")
+            return image_array
+
+    def preprocess_for_contours(self, image):
+        """Pre-process the image to make panel borders stand out for contour detection."""
+        gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
+
+        binary = cv2.adaptiveThreshold(
+            gray, 255,
+            cv2.ADAPTIVE_THRESH_MEAN_C,
+            cv2.THRESH_BINARY_INV,
+            21, 
+            8   
+        )
+
+        kernel = np.ones((5, 5), np.uint8)
+        closed = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel, iterations=2)
+
+        return closed
+
+    def find_panel_contours(self, processed_image, original_shape):
+        """Find and filter contours that are likely to be comic panels."""
+        contours, _ = cv2.findContours(processed_image, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+
+        height, width = original_shape[:2]
+        total_area = height * width
+        min_area = total_area * self.min_segment_area_ratio
+        max_area = total_area * self.max_segment_area_ratio
+
+        potential_panels = []
+        for contour in contours:
+            area = cv2.contourArea(contour)
+
+            if not (min_area < area < max_area):
+                continue
+
+            x, y, w, h = cv2.boundingRect(contour)
+
+            if h == 0: continue
+            aspect_ratio = w / h
+            if not (self.min_aspect_ratio < aspect_ratio < self.max_aspect_ratio):
+                continue
+
+            hull = cv2.convexHull(contour)
+            hull_area = cv2.contourArea(hull)
+            if hull_area == 0: continue
+            solidity = float(area) / hull_area
+            if solidity < self.min_solidity:
+                continue
+
+            potential_panels.append([x, y, x + w, y + h, area])
+
+        return np.array(potential_panels)
+
+    def apply_non_maximum_suppression(self, boxes):
+        """Apply NMS to merge overlapping bounding boxes."""
+        if len(boxes) == 0:
+            return []
+
+        boxes = boxes[boxes[:, 4].argsort()[::-1]]
+
+        picked_boxes = []
+        while len(boxes) > 0:
+            best_box = boxes[0]
+            picked_boxes.append(best_box)
+
+            remaining_boxes = boxes[1:]
+
+            x1 = np.maximum(best_box[0], remaining_boxes[:, 0])
+            y1 = np.maximum(best_box[1], remaining_boxes[:, 1])
+            x2 = np.minimum(best_box[2], remaining_boxes[:, 2])
+            y2 = np.minimum(best_box[3], remaining_boxes[:, 3])
+
+            inter_w = np.maximum(0, x2 - x1)
+            inter_h = np.maximum(0, y2 - y1)
+            intersection_area = inter_w * inter_h
+
+            best_box_area = (best_box[2] - best_box[0]) * (best_box[3] - best_box[1])
+            remaining_boxes_area = (remaining_boxes[:, 2] - remaining_boxes[:, 0]) * (remaining_boxes[:, 3] - remaining_boxes[:, 1])
+
+            union_area = best_box_area + remaining_boxes_area - intersection_area
+            iou = intersection_area / union_area
+
+            boxes = remaining_boxes[iou < self.nms_threshold]
+
+        return np.array(picked_boxes)
+
+    def split_collage(self, image_path, output_dir=None, debug=False):
+        """Main function to automatically split collage using contour detection and NMS."""
+        img = cv2.imread(str(image_path))
+        if img is None:
+            raise ValueError(f"Could not load image from {image_path}")
+
+        print(f"Processing image: {image_path}")
+        print(f"Image dimensions: {img.shape[1]}x{img.shape[0]}")
+
+        processed_image = self.preprocess_for_contours(img)
+        print("✓ Preprocessed image for contour detection")
+
+        potential_panels = self.find_panel_contours(processed_image, img.shape)
+        print(f"✓ Found {len(potential_panels)} potential panel contours")
+
+        final_panels = self.apply_non_maximum_suppression(potential_panels)
+        print(f"✓ Refined to {len(final_panels)} panels after Non-Maximum Suppression")
+
+        if len(final_panels) > 0:
+            img_height = img.shape[0]
+            panel_heights = [box[3] - box[1] for box in final_panels]
+            if panel_heights:
+                max_panel_height = max(panel_heights)
+
+                if max_panel_height > 0:
+                    bottom_margin = 10
+                    height_threshold_ratio = 0.8
+
+                    truly_final_panels = []
+                    for box in final_panels:
+                        h = box[3] - box[1]
+                        y2 = box[3]
+
+                        is_at_bottom = y2 >= (img_height - bottom_margin)
+                        is_too_short = h < (max_panel_height * height_threshold_ratio)
+
+                        if is_at_bottom and is_too_short:
+                            print(f"Skipping potentially incomplete panel at the bottom (h={h} vs max_h={max_panel_height})")
+                            continue
+                        truly_final_panels.append(box)
+
+                    final_panels = truly_final_panels
+
+        if len(final_panels) < 4:
+            print("⚠ Contour detection found too few panels. Creating fallback 2x2 grid...")
+            h, w = img.shape[:2]
+            final_panels = np.array([
+                [0, 0, w//2, h//2, 0],
+                [w//2, 0, w, h//2, 0],
+                [0, h//2, w//2, h, 0],
+                [w//2, h//2, w, h, 0]
+            ])
+
+        final_panels = sorted(final_panels, key=lambda b: (b[1], b[0]))
+
+        if output_dir is None:
+            output_dir = Path(image_path).parent / f"{Path(image_path).stem}_segments"
+        output_dir = Path(output_dir)
+        output_dir.mkdir(exist_ok=True)
+
+        saved_segments_info = []
+        for i, box in enumerate(final_panels):
+            x1, y1, x2, y2, _ = map(int, box)
+
+            padding = 3
+            x1 = max(0, x1 - padding)
+            y1 = max(0, y1 - padding)
+            x2 = min(img.shape[1], x2 + padding)
+            y2 = min(img.shape[0], y2 + padding)
+
+            segment = img[y1:y2, x1:x2]
+            original_dims = (segment.shape[1], segment.shape[0])
+
+            upscaled_segment_np = self._upscale_image(segment)
+
+            final_image = Image.fromarray(cv2.cvtColor(upscaled_segment_np, cv2.COLOR_BGR2RGB))
+
+            final_dims = (final_image.width, final_image.height)
+            output_path = output_dir / f"segment_{i+1:02d}.png"
+            final_image.save(str(output_path))
+
+            caption = (
+                f"Panel {i+1}<br>"
+                f"Original: {original_dims[0]}x{original_dims[1]}<br>"
+                f"Upscaled: {final_dims[0]}x{final_dims[1]}"
+            )
+
+            saved_segments_info.append({
+                "path": str(output_path),
+                "caption": caption
+            })
+            print(f"  Saved segment {i+1}: {final_dims[0]}x{final_dims[1]} pixels to {output_path}")
+
+        if debug:
+            debug_potential_panels = self.find_panel_contours(processed_image, img.shape)
+            self.create_debug_images(img, processed_image, debug_potential_panels, final_panels, output_dir)
+
+        print(f"\n🎉 Successfully split collage into {len(saved_segments_info)} segments!")
+        print(f"📁 Segments saved in: {output_dir}")
+        return saved_segments_info
+
+    def create_debug_images(self, original, processed, potential_boxes, final_boxes, output_dir):
+        """Create debug images showing the processing steps."""
+        cv2.imwrite(str(output_dir / "debug_01_binary_closed.png"), processed)
+
+        potential_img = original.copy()
+        if len(potential_boxes) > 0:
+            for x1, y1, x2, y2, _ in potential_boxes:
+                cv2.rectangle(potential_img, (int(x1), int(y1)), (int(x2), int(y2)), (0, 255, 255), 2)
+        cv2.imwrite(str(output_dir / "debug_02_potential_boxes.png"), potential_img)
+
+        final_img = original.copy()
+        if len(final_boxes) > 0:
+            for x1, y1, x2, y2, _ in final_boxes:
+                cv2.rectangle(final_img, (int(x1), int(y1)), (int(x2), int(y2)), (0, 255, 0), 3)
+        cv2.imwrite(str(output_dir / "debug_03_final_panels.png"), final_img)
+
+        print("🔍 Debug images saved:")
+        print("  - debug_01_binary_closed.png (preprocessed)")
+        print("  - debug_02_potential_boxes.png (before NMS)")
+        print("  - debug_03_final_panels.png (after NMS)")
+
+def main():
+    """Example usage"""
+    splitter = AutomatedCollageSplitter()
+
+    image_path = "path/to/your/comic_image.png"
+
+    try:
+        if not Path(image_path).exists():
+             print(f"❌ Image file not found: {image_path}")
+             print("Please update the image_path variable with the correct path to your collage image.")
+             return
+
+        segments = splitter.split_collage(
+            image_path=image_path,
+            debug=True
+        )
+
+        print(f"\n📊 Processing complete!")
+        print(f"Generated {len(segments)} separate images from the collage")
+
+    except Exception as e:
+        print(f"❌ Error processing image: {e}")
+        import traceback
+        traceback.print_exc()
+
+if __name__ == "__main__":
+    main()

notes.md

@@ -0,0 +1,41 @@
+# Image Processing Pipeline Notes
+
+## Task Tracking
+
+| Task | Status |
+|------|--------|
+| Split images correctly and discard half-generated images | ✅ |
+| Increase split images sizes | ✅ |
+| Upscale images and increase resolution | ✅ |
+| Ensure everything is working correctly | ✅ |
+| Review and adjust images | ✅ |
+| Use better Image processing techniques and models | ⬜ |
+
+## Original Task List
+1. Split the images correctly and discard half generated images.
+2. Increase split images sizes.
+3. Upscale images and increase resolution.
+4. Ensure everything is working correctly.
+
+## Process Flow
+
+```mermaid
+graph TD
+    A[Input Image] --> B[Split Images]
+    B --> C{Quality Check}
+    C -->|Good Quality| D[Size Increase]
+    C -->|Poor Quality| E[Discard]
+    D --> F[Upscale]
+    F --> G[Resolution Enhancement]
+    G --> H[Final Quality Check]
+    H -->|Pass| I[Final Image]
+    H -->|Fail| J[Review & Adjust]
+    J --> B
+```
+
+## Notes
+- ⬜ = Not Started/In Progress
+- ✅ = Completed
+- Update checkboxes as tasks are completed
+- Follow the process flow for each image processing task
+- Ensure quality checks are performed at each stage

requirements.txt

@@ -0,0 +1,11 @@
+gradio==5.35.0
+pillow==11.2.1
+python-dotenv==1.1.0
+google-generativeai==0.8.4
+google-auth-oauthlib==1.2.1
+google-api-python-client==2.166.0
+requests==2.32.3
+numpy==2.2.5
+openai==1.78.0
+opencv-contrib-python
+matplotlib

start.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+
+
+nohup python3 app.py > output.log 2>&1 &
+
+echo "starting server"
+

token.pickle

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3d9f3572ff848d00c9fdface71ac47338c510ae286d1dfd7128625eb75a5956a
+size 1002

ui/story_interface.py

@@ -0,0 +1,261 @@
+import gradio as gr
+import time
+from utils.story_management import (
+    generate_direct_comic,
+    extract_comic_scenes,
+    load_narration_from_file
+)
+from config import IMAGE_STYLES, IMAGE_STYLE_INFO, AGE_GROUPS
+from datetime import datetime
+
+def log_execution(func):
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        start_str = datetime.fromtimestamp(start_time).strftime('%Y-%m-%d %H:%M:%S')
+        
+        result = func(*args, **kwargs)
+        
+        end_time = time.time()
+        end_str = datetime.fromtimestamp(end_time).strftime('%Y-%m-%d %H:%M:%S')
+        duration = end_time - start_time
+        
+        # Write to file (works in Colab)
+        with open('content/logs.txt', 'a') as f:
+            f.write(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s\n")
+        
+        # Also print to see output immediately
+        print(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s")
+        
+        return result
+    return wrapper
+@log_execution
+def create_story_interface(demo: gr.Blocks) -> gr.Blocks:
+    """Create the main story interface with comic generation functionality.
+
+    This function initializes the primary UI interface for the comic generation system,
+    setting up the main tab structure and components.
+
+    Args:
+        demo (gr.Blocks): The Gradio Blocks instance to build the interface on
+
+    Returns:
+        gr.Blocks: The configured Gradio interface with all components initialized
+    """
+
+    create_quick_comic_tab()
+
+    return demo
+def create_quick_comic_tab() -> None:
+    """Create a simple tab for direct prompt-to-image comic generation.
+
+    Sets up the main comic generation interface with the following components:
+    - Story prompt input field
+    - AI prompt enhancement option
+    - Visual style selection
+    - Number of scenes selector
+    - Generation controls
+    - Image display area
+    - Scene navigation system
+
+    The interface allows users to:
+    1. Input their story description
+    2. Configure generation parameters
+    3. Generate a multi-panel comic
+    4. View and navigate through individual scenes
+    """
+
+    with gr.Column():
+    
+        gr.Markdown("Welcome to Hekaya ")
+
+        with gr.Row():
+            with gr.Column(scale=3):
+                user_prompt = gr.Textbox(
+                    label="What Hekaya story would you like to visualize?",
+                    placeholder="Describe your story with main characters and settings... (e.g., 'A young wizard learning magic in an ancient castle')",
+                    lines=4
+                )
+
+                enrich_prompt = gr.Checkbox(
+                    label="Enhance prompt with AI for coherence",
+                    value=True,
+                    info="Use AI to add just enough detail and coherence for consistent visual storytelling across all scenes"
+                )
+
+            with gr.Column(scale=1):
+                comic_style = gr.Dropdown(
+                    label="Visual Style",
+                    choices=IMAGE_STYLES,
+                    value="Comic Book Style"
+                )
+
+                style_description = gr.Markdown(
+                    value=f"*{IMAGE_STYLE_INFO['Comic Book Style']}*",
+                    label="Style Description"
+                )
+
+                age_group = gr.Dropdown(
+                    label="Target Age Group",
+                    choices=AGE_GROUPS,
+                    value="9-12 (Pre-teen)",
+                    info="Select the audience age group. Narration language, detail, and length will adapt automatically."
+                )
+
+                image_quality = gr.Dropdown(
+                    label="Image Quality",
+                    choices=["Low", "Medium", "High"],
+                    value="Low",
+                    info="Select the quality level for generated images. Higher quality may take longer to generate."
+                )
+
+        generate_btn = gr.Button("Generate Hekaya Story", variant="primary")
+        status_display = gr.Markdown("")
+
+        with gr.Row():
+            with gr.Column(scale=2):
+                comic_image = gr.Image(label="Generated Hekaya Story", type="filepath")
+
+            with gr.Column(scale=1, elem_id="save_info_container"):
+            
+                gr.Markdown("Your generated story images are automatically saved locally.")
+                save_path_display = gr.Markdown("", elem_id="save_path_info")
+
+        narration_display = gr.Markdown(
+        
+            visible=True,
+            elem_id="story_narration",
+            elem_classes=["story-narration-box"]
+        )
+
+        with gr.Column(visible=False) as scene_viewer_container:
+            
+            gr.Markdown("Use the navigation buttons to view each upscaled scene individually.")
+
+            with gr.Row(equal_height=True):
+                prev_scene_btn = gr.Button("← Previous Scene", variant="secondary")
+                scene_counter = gr.Markdown("Scene 1 of 1", elem_id="scene_counter")
+                next_scene_btn = gr.Button("Next Scene →", variant="secondary")
+
+            scene_image = gr.Image(label="Current Scene", type="filepath", height=768)
+            scene_caption_display = gr.Markdown("", elem_id="scene_caption", elem_classes=["scene-caption-box"])
+            scene_save_path = gr.Markdown("", elem_id="scene_save_path_info")
+
+        scene_info = gr.State([])
+        current_scene_index = gr.State(0)
+
+
+        def update_style_description(style: str) -> str:
+            """Update the style description text when a new style is selected."""
+            return f"*{IMAGE_STYLE_INFO[style]}*"
+
+        def show_generating_message() -> str:
+            """Display a loading message while story scenes are being generated."""
+            return "🔄 Generating your story scenes... Please wait..."
+
+        def generate_comic_with_length(user_prompt, comic_style, enrich_prompt, age_group, image_quality):
+            """Wrapper that handles the fixed num_scenes value while passing the age group and image quality."""
+            comic_image, save_path_display, status_display, narration = generate_direct_comic(
+                user_prompt,
+                comic_style,
+                12,
+                enrich_prompt,
+                3,  
+                age_group,
+            )
+
+            if narration and narration.strip():
+                narration_formatted = f""
+                narration_update = gr.update(visible=True, value=narration_formatted)
+            else:
+                narration_update = gr.update(visible=True, value="")
+
+            return comic_image, save_path_display, status_display, narration_update
+
+        def init_scene_viewer(comic_path: str | None) -> tuple:
+            """Initialize the scene viewer with extracted scenes from the comic image."""
+            if not comic_path:
+                return [], 0, gr.update(visible=False), None, "", "Scene 0 of 0", "No story image generated"
+
+            scene_data, save_message = extract_comic_scenes(comic_path, 0)
+
+            if not scene_data:
+                return [], 0, gr.update(visible=False), None, "", "Scene 0 of 0", "Failed to extract scenes"
+
+            first_scene = scene_data[0]
+
+            return (
+                scene_data,
+                0,
+                gr.update(visible=True),
+                first_scene['path'],
+                first_scene['caption'],
+                f"Scene 1 of {len(scene_data)}",
+                save_message
+            )
+
+        def update_scene_display(scene_data: list, current_index: int) -> tuple:
+            """Update the scene viewer display with the current scene."""
+            if not scene_data:
+                return None, "", "Scene 0 of 0"
+
+            index = max(0, min(current_index, len(scene_data) - 1))
+            scene = scene_data[index]
+
+            return scene['path'], scene['caption'], f"Scene {index + 1} of {len(scene_data)}"
+
+        def navigate_to_previous_scene(idx: int) -> int:
+            """Navigate to the previous scene in the sequence."""
+            return max(0, idx - 1)
+
+        def navigate_to_next_scene(paths: list, idx: int) -> int:
+            """Navigate to the next scene in the sequence."""
+            return min(len(paths) - 1, idx + 1) if paths else 0
+
+
+        comic_style.change(
+            fn=update_style_description,
+            inputs=[comic_style],
+            outputs=[style_description]
+        )
+
+        generate_btn.click(
+            fn=show_generating_message,
+            inputs=None,
+            outputs=status_display
+        ).then(
+            fn=generate_comic_with_length,
+            inputs=[user_prompt, comic_style, enrich_prompt, age_group, image_quality],
+            outputs=[comic_image, save_path_display, status_display, narration_display]
+        ).then(
+            fn=init_scene_viewer,
+            inputs=[comic_image],
+            outputs=[
+                scene_info,
+                current_scene_index,
+                scene_viewer_container,
+                scene_image,
+                scene_caption_display,
+                scene_counter,
+                scene_save_path
+            ]
+        )
+
+        prev_scene_btn.click(
+            fn=navigate_to_previous_scene,
+            inputs=[current_scene_index],
+            outputs=[current_scene_index]
+        ).then(
+            fn=update_scene_display,
+            inputs=[scene_info, current_scene_index],
+            outputs=[scene_image, scene_caption_display, scene_counter]
+        )
+
+        next_scene_btn.click(
+            fn=navigate_to_next_scene,
+            inputs=[scene_info, current_scene_index],
+            outputs=[current_scene_index]
+        ).then(
+            fn=update_scene_display,
+            inputs=[scene_info, current_scene_index],
+            outputs=[scene_image, scene_caption_display, scene_counter]
+        )

utils/comic_panel_splitter.py

@@ -0,0 +1,80 @@
+import cv2
+import numpy as np
+import os
+import time
+from datetime import datetime
+
+
+def log_execution(func):
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        start_str = datetime.fromtimestamp(start_time).strftime('%Y-%m-%d %H:%M:%S')
+        
+        result = func(*args, **kwargs)
+        
+        end_time = time.time()
+        end_str = datetime.fromtimestamp(end_time).strftime('%Y-%m-%d %H:%M:%S')
+        duration = end_time - start_time
+        
+        # Write to file (works in Colab)
+        with open('content/logs.txt', 'a') as f:
+            f.write(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s\n")
+        
+        # Also print to see output immediately
+        print(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s")
+        
+        return result
+    return wrapper
+
+@log_execution
+def split_comic_panels(image_path, output_dir):
+    img = cv2.imread(image_path)
+    if img is None:
+        print(f"Error: Could not read image from {image_path}")
+        return
+
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+
+    th = cv2.adaptiveThreshold(gray, 255,
+        cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY_INV,
+        blockSize=51, C=10)
+    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (15,15))
+    clean = cv2.morphologyEx(th, cv2.MORPH_CLOSE, kernel)
+
+    cnts, _ = cv2.findContours(clean, cv2.RETR_EXTERNAL,
+                               cv2.CHAIN_APPROX_SIMPLE) 
+    panels = []
+    for c in cnts:
+        area = cv2.contourArea(c)
+        if area < 10000:  
+            continue
+        peri = cv2.arcLength(c, True)
+        approx = cv2.approxPolyDP(c, 0.02 * peri, True)
+        panels.append((cv2.boundingRect(approx), c))
+    @log_execution
+    def panel_key(item):
+        (x,y,w,h), _ = item
+        return (y//50, x)  
+
+    panels_sorted = sorted(panels, key=panel_key)
+
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+        
+    for i, ((x,y,w,h), contour) in enumerate(panels_sorted, 1):
+        crop = img[y:y+h, x:x+w]
+        cv2.imwrite(os.path.join(output_dir, f"panel_{i:02d}.png"), crop)
+
+if __name__ == "__main__":
+    if not os.path.exists("comic_page.jpg"):
+        dummy_image = np.zeros((600, 800, 3), dtype=np.uint8)
+        cv2.putText(dummy_image, "Comic Page", (300, 300), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2, cv2.LINE_AA)
+        cv2.rectangle(dummy_image, (50, 50), (350, 250), (255,255,255), 5) 
+        cv2.rectangle(dummy_image, (400, 50), (750, 250), (255,255,255), 5) 
+        cv2.rectangle(dummy_image, (50, 300), (750, 550), (255,255,255), 5) 
+        cv2.imwrite("comic_page.jpg", dummy_image)
+
+    if not os.path.exists("output_panels"):
+        os.makedirs("output_panels")
+    split_comic_panels("comic_page.jpg", "output_panels")
+    print("Comic panels split and saved to output_panels directory.") 

utils/story_management.py

@@ -0,0 +1,455 @@
+import os
+import json
+import base64
+import time
+from models.story_generator import StoryGenerator
+from models.comic_image_generator import ComicImageGenerator
+from datetime import datetime
+from PIL import Image
+import io
+from google.generativeai import GenerativeModel, configure
+import config
+from new_image_splitting import AutomatedCollageSplitter
+
+
+def log_execution(func):
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        start_str = datetime.fromtimestamp(start_time).strftime('%Y-%m-%d %H:%M:%S')
+        
+        result = func(*args, **kwargs)
+        
+        end_time = time.time()
+        end_str = datetime.fromtimestamp(end_time).strftime('%Y-%m-%d %H:%M:%S')
+        duration = end_time - start_time
+        
+        # Write to file (works in Colab)
+        with open('content/logs.txt', 'a') as f:
+            f.write(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s\n")
+        
+        # Also print to see output immediately
+        print(f"{func.__name__}, start: {start_str}, end: {end_str}, duration: {duration:.4f}s")
+        
+        return result
+    return wrapper
+@log_execution
+def save_image_from_data_url(data_url, filename):
+    """Save an image from a data URL to a file."""
+    if not data_url or not data_url.startswith("data:image"):
+        print(f"Invalid data URL: {data_url[:30] if data_url else None}")
+        return False
+
+    try:
+        image_data = data_url.split(",")[1]
+        image_bytes = base64.b64decode(image_data)
+
+        os.makedirs(os.path.dirname(filename), exist_ok=True)
+
+        with open(filename, "wb") as f:
+            f.write(image_bytes)
+
+        return True
+    except Exception as e:
+        print(f"Error saving image: {e}")
+        return False
+@log_execution
+def generate_direct_comic(
+    user_prompt,
+    image_style=None,
+    num_scenes: int = 12,
+    enrich_prompt=True,
+    narration_length=3,
+    age_group: str | None = None,
+):
+    """
+    Generate a comic directly from a user prompt with optional story enhancement.
+
+    NOTE: The system is now standardized to generate exactly 12 scenes arranged in a 3×4 grid. Any value passed into
+    `num_scenes` will be overridden to maintain this consistency.
+
+    Args:
+        user_prompt: The user's description of what they want in the comic
+        image_style: Style to use for comic generation
+        num_scenes: Ignored—kept for backward compatibility. Always forced to 12.
+        enrich_prompt: Whether to enhance the prompt using Gemini AI
+        narration_length: Length of narration (1=Brief, 2=Medium, 3=Detailed, 4=Very Detailed)
+        age_group: Target age group that determines the language complexity (e.g., "6-8 (Kids)")
+
+    Returns:
+        comic_output_path: Path to the generated comic image
+        save_path_display: Display message about where the image was saved
+        status_display: Status message about generation success/failure
+        narration: Generated story narration
+    """
+    start_time = time.time()
+
+    try:
+        if not user_prompt or len(user_prompt.strip()) == 0:
+            raise ValueError("User prompt cannot be empty")
+
+        user_prompt = user_prompt.strip()
+        if len(user_prompt) > 10000:  
+            user_prompt = user_prompt[:10000] + "..."
+            print("⚠️ Prompt truncated to prevent processing issues")
+
+        num_scenes = 12
+
+        if enrich_prompt:
+            try:
+                story_generator = StoryGenerator()
+
+                print(f"Enhancing user prompt: {user_prompt[:100]}...")
+                enhanced_description = story_generator.enhance_user_story(user_prompt)
+
+                if enhanced_description and len(enhanced_description.strip()) > 0:
+                    print(f"Prompt successfully enhanced")
+                    final_prompt = enhanced_description
+                else:
+                    print("⚠️ Enhancement failed, using original prompt")
+                    final_prompt = user_prompt
+
+            except Exception as enhancement_error:
+                print(f"⚠️ Story enhancement failed: {enhancement_error}")
+                print("Using original prompt without enhancement")
+                final_prompt = user_prompt
+        else:
+            print(f"Using original prompt without enhancement: {user_prompt[:100]}...")
+            final_prompt = user_prompt
+
+        try:
+            image_generator = ComicImageGenerator()
+        except Exception as generator_error:
+            print(f"❌ Failed to create image generator: {generator_error}")
+            raise generator_error
+
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        safe_title = "".join(c if c.isalnum() or c in [' ', '_', '-'] else '_' for c in user_prompt[:20])
+        safe_title = safe_title.strip().replace(" ", "_")
+        if not safe_title:
+            safe_title = "story"
+
+        image_dir = f"Story-Generation/generated/images/{safe_title}_{timestamp}"
+        try:
+            os.makedirs(image_dir, exist_ok=True)
+        except Exception as dir_error:
+            print(f"❌ Failed to create directory: {dir_error}")
+            image_dir = f"{safe_title}_{timestamp}"
+            os.makedirs(image_dir, exist_ok=True)
+
+        comic_output_path = os.path.join(image_dir, f"story_scenes.png")
+
+        try:
+            comic_image, data_url = image_generator.generate_comic(
+                {
+                    "title": safe_title,
+                    "description": final_prompt,
+                    "num_scenes": num_scenes  
+                },
+                output_path=comic_output_path,
+                style=image_style
+            )
+
+            if comic_image is None and data_url is None:
+                raise ValueError("Comic generation returned no results")
+
+        except Exception as generation_error:
+            print(f"❌ Comic generation failed: {generation_error}")
+            raise generation_error
+
+        if age_group:
+            age_to_length = {
+                "3-5 (Pre-school)": 1,
+                "6-8 (Kids)": 2,
+                "9-12 (Pre-teen)": 3,
+                "13-18 (Teen)": 3,
+                "18+ (Adult)": 4,
+            }
+
+            mapped_length = age_to_length.get(age_group)
+            if mapped_length is not None:
+                narration_length = mapped_length
+
+        narration = ""
+        if comic_output_path and os.path.exists(comic_output_path):
+            try:
+                narration = generate_image_narration(
+                    comic_output_path, narration_length, age_group=age_group
+                )
+                if narration:
+                    narration_path = os.path.join(image_dir, "narration.txt")
+                    with open(narration_path, "w", encoding="utf-8") as f:
+                        f.write(narration)
+                    print(f"💾 Narration saved to: {narration_path}")
+            except Exception as narration_error:
+                print(f"⚠️ Narration generation failed: {narration_error}")
+                narration = ""
+
+        end_time = time.time()
+        generation_time = end_time - start_time
+
+        try:
+            absolute_path = os.path.abspath(comic_output_path)
+        except Exception:
+            absolute_path = comic_output_path
+
+        enhancement_status = "with AI enhancement" if enrich_prompt else "using original prompt"
+        save_message = f"""
+        <div style="padding: 10px; border: 1px solid 
+            <p><strong>💾 Story Scenes Saved Successfully</strong></p>
+            <p>Generated {enhancement_status}</p>
+            <p>Location: <code>{absolute_path}</code></p>
+            <p>You can find all your saved story images in the images directory.</p>
+        </div>
+        """
+
+        return (
+            comic_output_path,
+            save_message,
+            f"✅ Story scenes generated successfully in {generation_time:.2f} seconds!",
+            narration
+        )
+
+    except Exception as e:
+        import traceback
+        error_details = traceback.format_exc()
+        print(f"❌ Error generating story scenes: {e}")
+        print(f"Full error details: {error_details}")
+
+        return None, "", f"❌ Error generating story scenes: {str(e)}", ""
+
+@log_execution
+def extract_comic_scenes(comic_image_path, num_scenes):
+    """
+    Extract individual scenes from a story image and save them as separate files.
+    This version uses the AutomatedCollageSplitter.
+
+    Args:
+        comic_image_path: Path to the story image
+        num_scenes: This parameter is kept for compatibility but is not used
+                    by the automated splitter.
+
+    Returns:
+        list: List of paths to the individual scene images
+        str: Display message about where the scenes were saved
+    """
+    if not comic_image_path or not os.path.exists(comic_image_path):
+        return [], "Error: Comic image not found."
+
+    try:
+        base_dir = os.path.dirname(comic_image_path)
+        image_stem = os.path.splitext(os.path.basename(comic_image_path))[0]
+        output_dir = os.path.join(base_dir, f"{image_stem}_segments")
+
+        splitter = AutomatedCollageSplitter()
+
+        scene_info = splitter.split_collage(
+            image_path=comic_image_path,
+            output_dir=output_dir,
+            debug=False 
+        )
+
+        if not scene_info:
+            return [], "Automated splitting failed to find any panels."
+
+        scene_paths = [info['path'] for info in scene_info]
+
+        save_message = f"""
+        <div style="padding: 10px; border: 1px solid 
+            <p><strong>💾 Individual Scenes Saved Successfully</strong></p>
+            <p>Found and saved {len(scene_paths)} scenes.</p>
+            <p>Location: <code>{os.path.abspath(output_dir)}</code></p>
+        </div>
+        """
+
+        return scene_info, save_message
+
+    except Exception as e:
+        import traceback
+        error_details = traceback.format_exc()
+        print(f"❌ Error extracting scenes: {e}")
+        print(f"Full error details: {error_details}")
+        return [], f"Error extracting scenes: {e}"
+@log_execution
+def generate_image_narration(image_path, narration_length=3, age_group: str | None = None):
+    """
+    Generate detailed story narration that actually tells the story shown in the comic panels.
+
+    Args:
+        image_path: Path to the generated comic image
+        narration_length: Length of narration (1=Brief, 2=Medium, 3=Detailed, 4=Very Detailed)
+        age_group: Optional target age group string that informs the language difficulty
+
+    Returns:
+        str: Generated detailed narration text or empty string if failed
+    """
+    try:
+        configure(api_key=config.GOOGLE_API_KEY)
+
+        model = GenerativeModel('gemini-2.5-flash')
+
+        comic_image = Image.open(image_path)
+
+        length_specs = {
+            1: {
+                "description": "Quick scene summary",
+                "min_chars": 100,
+                "style": "concise, 2-3 lines per scene - capture the essence and emotion of each moment"
+            },
+            2: {
+                "description": "Brief scene descriptions",
+                "min_chars": 200,
+                "style": "short and engaging, 2-3 lines per scene - focus on key actions and feelings"
+            },
+            3: {
+                "description": "Quick narrative",
+                "min_chars": 300,
+                "style": "brief but vivid, 2-3 lines per scene - capture emotion, action, and atmosphere"
+            },
+            4: {
+                "description": "Concise story flow",
+                "min_chars": 400,
+                "style": "quick and immersive, 2-3 lines per scene - paint rich pictures efficiently"
+            }
+        }
+
+        spec = length_specs.get(narration_length, length_specs[3])
+
+        age_group_specs = {
+            "3-5 (Pre-school)": {
+                "audience": "very young children ages 3-5",
+                "language": "Narrate like a playful adult reading aloud. Use extremely simple words, cheerful tone, repetition, and lots of sound effects and emotions."
+            },
+            "6-8 (Kids)": {
+                "audience": "children ages 6-8",
+                "language": "Use an enthusiastic and descriptive tone. Keep vocabulary simple but expressive. Include action, feelings, and dialogue they can relate to."
+            },
+            "9-12 (Pre-teen)": {
+                "audience": "pre-teens ages 9-12",
+                "language": "Use a lively, adventurous tone with accessible vocabulary. Add humor, suspense, and vivid action to keep engagement high."
+            },
+            "13-18 (Teen)": {
+                "audience": "teenagers ages 13-18",
+                "language": "Use present-tense narration with emotional depth and realism. Include internal thoughts, intense scenes, and natural dialogue."
+            },
+            "18+ (Adult)": {
+                "audience": "adults",
+                "language": "Use mature, nuanced storytelling. Allow complex emotions, sensory detail, and deeper themes to emerge naturally."
+            }
+        }
+
+        selected_age_spec = age_group_specs.get(age_group) if age_group else None
+
+        audience_desc = selected_age_spec['audience'] if selected_age_spec else "a general audience"
+        language_guideline = selected_age_spec['language'] if selected_age_spec else "Use vivid, engaging language appropriate to the story."
+
+        narration_mode = "Provide quick, engaging narration with 2-3 lines per scene. Each scene gets 2-3 concise, standalone sentences that capture the key moment, emotion, and atmosphere. Do NOT prefix scenes with 'Scene'"
+
+        narration_prompt = f"""
+        You are a concise narrator creating quick scene descriptions for {audience_desc}.
+
+        **NARRATION STYLE:**
+        {narration_mode}
+
+        **FORMAT REQUIREMENTS:**
+        • Identify each distinct scene and write 2-3 sentences (2 minimum, 3 maximum) **without** any numeric prefixes or headings.
+        • First sentence: What's happening (action/event)
+        • Second sentence: How it feels or what it means (emotion/impact)
+        • Optional third sentence: Additional detail or atmosphere
+        • Keep each sentence under 20 words
+        • Use present tense and active voice
+        • Separate scenes with a blank line for readability
+        • Make it flow naturally from scene to scene
+
+        **EXAMPLE FORMAT:**
+        The cat stretches lazily in the morning sunlight streaming through the window. A new day full of adventure awaits her curious spirit.
+
+        She bounds toward the garden gate with graceful excitement. Something magical calls to her curious heart.
+
+        **STYLE:** {spec['style']}
+        **LANGUAGE:** {language_guideline}
+
+        Now provide your quick, 2-line narration for each scene. Remember: NO headings or prefixes, just the narration lines separated by blank lines:
+        """
+
+        print(f"🔍 Generating {spec['description']} using Gemini Vision...")
+
+        response = model.generate_content([narration_prompt, comic_image])
+        narration = response.text.strip()
+
+        if narration:
+            narration = narration.strip('"\'`')
+
+            lines = narration.split('\n')
+            clean_lines = []
+            import re
+            for line in lines:
+                line = line.strip()
+                if not line:
+                    continue
+
+                if line.startswith(('Note:', 'Remember:', 'Format:', 'Your narration should:', 'Think of this as')):
+                    continue
+
+                line = re.sub(r'^Scene\s*\d+\s*[:.\-]\s*', '', line, flags=re.IGNORECASE)
+
+                clean_lines.append(line)
+
+            narration = '\n\n'.join(clean_lines)
+
+            if len(narration) < spec['min_chars']:
+                print(f"⚠️ Initial narration too short for selected length, requesting more detail...")
+
+                detailed_prompt = f"""
+                The narration needs to be more detailed while keeping the concise 2-line-per-scene format.
+
+                CURRENT NARRATION:
+                {narration}
+
+                Expand this following the same format:
+                • **Style:** {narration_mode}
+                • **Format:** 2-3 lines per scene, but make them more vivid and detailed
+                • **Voice:** {spec['style']}
+                • **Language:** {language_guideline}
+                • **Focus:** Keep it concise but add more sensory details, emotion, and atmosphere
+
+                Provide the enhanced 2-3-lines-per-scene narration:
+                """
+
+                response = model.generate_content(detailed_prompt)
+                expanded_narration = response.text.strip()
+                if expanded_narration and len(expanded_narration) > len(narration):
+                    narration = expanded_narration.strip('"\'`')
+
+            print(f"✅ Generated {spec['description']}: {len(narration)} characters")
+            return narration
+
+    except Exception as e:
+        print(f"⚠️ Failed to generate narration: {e}")
+
+    return ""
+@log_execution
+def load_narration_from_file(comic_image_path):
+    """
+    Load narration from the saved narration.txt file for a given comic image.
+
+    Args:
+        comic_image_path: Path to the comic image
+
+    Returns:
+        str: Loaded narration text or empty string if not found
+    """
+    try:
+        if not comic_image_path:
+            return ""
+
+        image_dir = os.path.dirname(comic_image_path)
+        narration_path = os.path.join(image_dir, "narration.txt")
+
+        if os.path.exists(narration_path):
+            with open(narration_path, "r", encoding="utf-8") as f:
+                narration = f.read().strip()
+            return narration
+    except Exception as e:
+        print(f"⚠️ Could not load narration: {e}")
+
+    return ""