Deploy from stable branch

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+<!--
+Thank you for your pull request. Please review and complete the sections below.
+-->
+
+### Description
+
+<!-- Provide a description of the change or tick the promote to stable box -->
+
+- [ ] Promote QA to Stable
+
+### Checklist
+
+<!-- For completed items, change [ ] to [x]. -->
+
+- [ ] I have installed pre-commit: `pre-commit install`
+- [ ] All pre-commit checks pass: `pre-commit run`
+- [ ] Dependencies are [compatible with ZeroGPU](https://huggingface.co/docs/hub/en/spaces-zerogpu#supported-versions)

.gitignore

@@ -0,0 +1,173 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# 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/
+
+
+# Boilerplate specific ignores
+.gradio/
+.ruff_cache/

.gitlint

@@ -0,0 +1,143 @@
+# Edit this file as you like.
+#
+# All these sections are optional. Each section with the exception of [general] represents
+# one rule and each key in it is an option for that specific rule.
+#
+# Rules and sections can be referenced by their full name or by id. For example
+# section "[body-max-line-length]" could also be written as "[B1]". Full section names are
+# used in here for clarity.
+#
+# [general]
+# Ignore certain rules, this example uses both full name and id
+# ignore=title-trailing-punctuation, T3
+
+[general]
+# You HAVE to add the rule here to enable it, only configuring (such as below)
+# does NOT enable it.
+contrib=contrib-title-conventional-commits
+
+[contrib-title-conventional-commits]
+# Specify allowed commit types. For details see: https://www.conventionalcommits.org/
+types = build,chore,ci,docs,feat,fix,perf,refactor,revert,style,test
+
+# verbosity should be a value between 1 and 3, the commandline -v flags take precedence over this
+# verbosity = 2
+
+# By default gitlint will ignore merge, revert, fixup and squash commits.
+# ignore-merge-commits=true
+# ignore-revert-commits=true
+# ignore-fixup-commits=true
+# ignore-squash-commits=true
+
+# Ignore any data send to gitlint via stdin
+# ignore-stdin=true
+
+# Fetch additional meta-data from the local repository when manually passing a
+# commit message to gitlint via stdin or --commit-msg. Disabled by default.
+# staged=true
+
+# Hard fail when the target commit range is empty. Note that gitlint will
+# already fail by default on invalid commit ranges. This option is specifically
+# to tell gitlint to fail on *valid but empty* commit ranges.
+# Disabled by default.
+# fail-without-commits=true
+
+# Enable debug mode (prints more output). Disabled by default.
+# debug=true
+
+# Enable community contributed rules
+# See http://jorisroovers.github.io/gitlint/contrib_rules for details
+# contrib=contrib-title-conventional-commits,CC1
+
+# Set the extra-path where gitlint will search for user defined rules
+# See http://jorisroovers.github.io/gitlint/user_defined_rules for details
+# extra-path=examples/
+
+# This is an example of how to configure the "title-max-length" rule and
+# set the line-length it enforces to 50
+# [title-max-length]
+# line-length=50
+
+# Conversely, you can also enforce minimal length of a title with the
+# "title-min-length" rule:
+# [title-min-length]
+# min-length=5
+
+# [title-must-not-contain-word]
+# Comma-separated list of words that should not occur in the title. Matching is case
+# insensitive. It's fine if the keyword occurs as part of a larger word (so "WIPING"
+# will not cause a violation, but "WIP: my title" will.
+# words=wip
+
+# [title-match-regex]
+# python-style regex that the commit-msg title must match
+# Note that the regex can contradict with other rules if not used correctly
+# (e.g. title-must-not-contain-word).
+# regex=^US[0-9]*
+
+# [body-max-line-length]
+# line-length=72
+
+# [body-min-length]
+# min-length=5
+
+# [body-is-missing]
+# Whether to ignore this rule on merge commits (which typically only have a title)
+# default = True
+# ignore-merge-commits=false
+
+# [body-changed-file-mention]
+# List of files that need to be explicitly mentioned in the body when they are changed
+# This is useful for when developers often erroneously edit certain files or git submodules.
+# By specifying this rule, developers can only change the file when they explicitly reference
+# it in the commit message.
+# files=gitlint-core/gitlint/rules.py,README.md
+
+# [body-match-regex]
+# python-style regex that the commit-msg body must match.
+# E.g. body must end in My-Commit-Tag: foo
+# regex=My-Commit-Tag: foo$
+
+# [author-valid-email]
+# python-style regex that the commit author email address must match.
+# For example, use the following regex if you only want to allow email addresses from foo.com
+# regex=[^@]+@foo.com
+
+# [ignore-by-title]
+# Ignore certain rules for commits of which the title matches a regex
+# E.g. Match commit titles that start with "Release"
+# regex=^Release(.*)
+
+# Ignore certain rules, you can reference them by their id or by their full name
+# Use 'all' to ignore all rules
+# ignore=T1,body-min-length
+
+# [ignore-by-body]
+# Ignore certain rules for commits of which the body has a line that matches a regex
+# E.g. Match bodies that have a line that that contain "release"
+# regex=(.*)release(.*)
+#
+# Ignore certain rules, you can reference them by their id or by their full name
+# Use 'all' to ignore all rules
+# ignore=T1,body-min-length
+
+# [ignore-body-lines]
+# Ignore certain lines in a commit body that match a regex.
+# E.g. Ignore all lines that start with 'Co-Authored-By'
+# regex=^Co-Authored-By
+
+# [ignore-by-author-name]
+# Ignore certain rules for commits of which the author name matches a regex
+# E.g. Match commits made by dependabot
+# regex=(.*)dependabot(.*)
+#
+# Ignore certain rules, you can reference them by their id or by their full name
+# Use 'all' to ignore all rules
+# ignore=T1,body-min-length
+
+# This is a contrib rule - a community contributed rule. These are disabled by default.
+# You need to explicitly enable them one-by-one by adding them to the "contrib" option
+# under [general] section above.
+# [contrib-title-conventional-commits]
+# Specify allowed commit types. For details see: https://www.conventionalcommits.org/
+# types = bugfix,user-story,epic

.pre-commit-config.yaml

@@ -0,0 +1,51 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-ast
+      - id: check-case-conflict
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: end-of-file-fixer
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.11.8
+    hooks:
+      - id: ruff
+  - repo: https://github.com/pycqa/isort
+    rev: 6.0.1
+    hooks:
+      - id: isort
+        args: ["--profile", "black"]
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.19.1
+    hooks:
+      - id: pyupgrade
+        args: ["--py310-plus"]
+  - repo: https://github.com/psf/black
+    rev: 25.1.0
+    hooks:
+      - id: black
+        args:
+          - --line-length=120
+  - repo: https://github.com/jorisroovers/gitlint
+    rev:  v0.19.1
+    hooks:
+    -   id: gitlint
+        name: gitlint
+        language: python
+        entry: gitlint
+        args: [--staged, --msg-filename]
+        stages: [commit-msg]
+  - repo: https://github.com/python-poetry/poetry
+    rev: '1.8.0'
+    hooks:
+      - id: poetry-check
+      - id: poetry-lock
+        args: [--no-update]
+        language_version: "3.10"
+      - id: poetry-export
+        name: poetry export for base requirements
+        args: [-f, requirements.txt, -o, requirements.txt, -n, --only=main, --without-hashes]

DEVELOPMENT.md

@@ -0,0 +1,176 @@
+# IBM Research Hugging Face Spaces gradio template
+
+This template repository lets you quickly build a [gradio](https://www.gradio.app/) Hugging Face spaces demo for the [ibm-granite org](https://huggingface.co/ibm-granite). It is set up with the requirements, theming and analytics for the ibm-granite org as well as pre-commit hooks and linting configuration to maintain a consistent code standard across all demos.
+
+## 👩‍💻 Introduction
+
+To deploy demos to the ibm-granite org on Hugging Face, you will be working with the Research Design Technical Experiences (RDTE) team via this GitHub org. You will not gain access to the ibm-granite Hugging Face org as there are limited seats available. Hence, you will work via the RDTE team (who have write access) to create and deploy demos to Hugging Face.
+
+## 🛠️ Getting started
+
+This is the place to start when building gradio demos for IBM Granite. Complete the following steps to get a repository set up and configured for your demo as well as the deployment pipeline to validate and push it to Hugging Face spaces.
+
+1. [Raise an onboarding request](https://github.ibm.com/ibm-huggingface-space-demos/deployment/issues/new?assignees=james-sutton,gwhite&labels=onboarding%2Ctriage&projects=&template=onboarding.yaml&title=%5BOnboarding%5D%3A+). Please fill the templated onboarding request to get a new repository set up for you in this org and to give access to anything else required.
+2. Once your repository has been created, please either update it with your existing demo if you have one, or have a play with the example and modify it to create your new demo. You'll be working in the `main` branch whilst developing your demo. Your `main` branch is linked to the "QA" instance of your demo in the IBM org on Hugging Face.
+3. Make sure that you follow this development guide and use the pre-configured pre-commit hooks before every commit and push.
+4. Once you are happy with your demo and want to get it deployed into production on Hugging Face spaces in the ibm-granite org, open a pull request to merge the `main` branch into the `stable` branch. The RDTE team will validate the demo works well both from a technical and UX standpoint. If your demo needs any custom environment variables or secrets, let the RDTE team know and we will contact you directly to get them added to the Space configuration on Hugging Face.
+5. Once the Pull request has been approved, you can merge it into the `stable` branch. A deployment will then push your changes to Hugging Face spaces where it will build and become available for use. Initially, both the "QA" and "Production" versions of your demo will be marked as private and only visible to members of the ibm-research org (QA) and ibm-granite org (production) that have logged into Hugging Face. The "QA" version will always remain private in the ibm-research org. However, when the RDTE team are happy to publish the demo to stable, they will mark the "Production" version as public in the ibm-granite org.
+
+### Onboarding Process Summary
+
+The following diagram explains the onboarding process. Actions that you, the developer, take are shown in darker blue. Actions that we, the RDTE team, take are shown in lighter blue. The lighter blue steps that have darker borders are automations maintained by the RDTE team, these steps require no manual intervention.
+
+```mermaid
+flowchart TD
+    1[Developer opens onboarding ticket in GHE Org]:::developer-->2
+    2{RDTE team review the request}:::rdte--Request returned with comments-->1
+    2--Approved-->3
+    3[Developer is invited to join the ibm-research org on HF]:::rdte-->4
+    4[New git repository created from template and configured]:::rdte-->5
+    5[QA HF space created in IBM org]:::rdte-->6
+    6[Developers push commits to main branch]:::developer-->7
+    7-->6
+    7[Main branch deployed to QA space in ibm-granite org on HF]:::rdteauto-->8
+    8[Developers open/update PR to merge main branch to stable branch]:::developer-->9
+    9{PR review}:::rdte--PR Approved-->10
+    9--Changes requested-->6
+    10{Prod space exists?}:::rdte-- Yes -->12
+    10-- No -->11
+    11[Prod HF space created in ibm-granite org]:::rdte-->12
+    12[Merge PR]:::developer-->13
+    13[Stable branch deployed to prod space in ibm-granite org on HF]:::rdteauto
+    classDef rdte fill:#EDF5FF,stroke:#D0E2FF,color:#000;
+    classDef rdteauto fill:#EDF5FF,stroke:#78A9FF,color:#000;
+    classDef developer fill:#A6C8FF,stroke:#78A9FF,color:#000;
+```
+
+## 🛠️ Development guide
+
+Further information on developing the code in this repository is provided below.
+
+### Clone your code repository
+
+Once you have been notified that your code repository has been created in this org, you can clone it to your local machine and start work.
+
+If you just want to play with our template, you're welcome to [use it](https://github.ibm.com/new?template_name=gradio-template&template_owner=ibm-huggingface-space-demos) to create a new code repository in another org. Later, for deployment, you wil need to move your code to the repository created in this org.
+
+### Prerequisites
+
+Some things you will need to do on your machine before developing.
+
+#### Precommit
+
+[Precommit](https://pre-commit.com) is a tool that adds git commit hooks. You will need to [install](https://pre-commit.com/#install) it on your machine and then run within your code repository:
+
+```shell
+pre-commit install
+```
+
+You can manually run pre-commit using the following command:
+
+```shell
+# To run against staged files:
+pre-commit run
+
+# If you want to run against staged and unstaged files:
+pre-commit run --all-files
+```
+
+It is important to run the pre-commit hooks and fix any files that fail before you commit and push to the repository as the pull request build will fail any PR that does not adhere to them i.e. the RDTE team will only accept your code for deployment to Hugging Face once it has passed all of the pre-commit checks.
+
+#### Poetry
+
+[Poetry](https://python-poetry.org/) is a tool for Python packaging, dependency and virtual environment management that is used to manage the development of this project. You will need to install Poetry locally. There are several ways to install it including through the package manager of your operating system, however, the easiest way to install is likely using their installer, as follows:
+
+```shell
+curl -sSL https://install.python-poetry.org | python3 -
+```
+
+You can also use `pip` and `pipx` to install poetry, the details of which are at https://python-poetry.org/docs/
+
+Once installed, the project is configured and controlled via the `pyproject.toml` file with the current dependency tree stored in `poetry.lock`. You may also [configure poetry](https://python-poetry.org/docs/configuration/) further if you wish but there is no need to do so as the default options are sufficient. You may, however, wish to change some of the options set in this template:
+| Setting | Notes |
+| ------- | ----- |
+| name | **Update this**, to reflect the name of your demo |
+| version | **Update this**, to reflect the current version of your demo |
+| description | **Update this**, to a short description of your demo |
+| authors | **Update this**, to the list of authors of your demo |
+
+## 🛠️ Install and run locally
+
+To get set up ready to run the code in development mode:
+
+```shell
+# add the poetry shell and export plugins (you only need to do this once on your machine)
+poetry self add poetry-plugin-shell
+poetry self add poetry-plugin-export
+
+# create and activate a python virtual environment
+poetry shell
+poetry install
+
+# run the demo locally (for development with automatic reload)
+gradio src/app.py
+```
+
+## 📝 Documenting your demo
+
+If you would like to write some information/documentation about your demo that is intended for developers or other people that might want to run the demo from scratch, please use the [README.md](README.md) file, leaving the Hugging Face Spaces configuration header in place at the top of the file.
+
+### Hugging face spaces configuration settings
+
+Hugging Face allow the configuration of spaces demonstrations via the [README.md](README.md) file in the root of the project. There is a [Spaces Configuration Reference](https://huggingface.co/docs/hub/en/spaces-config-reference) guide that you can use to gain an understanding of the configuration options that can be specified here.
+
+The template has a set of initial defaults, similar to these:
+
+```
+---
+title: Granite 3.0 Chat
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.9.1
+app_file: src/app.py
+pinned: false
+license: apache-2.0
+short_description: Chat with IBM Granite 3.0
+---
+```
+
+#### Options
+
+The default options specified above:
+| Setting | Notes |
+| ------- | ----- |
+| title | **Update this**, keep this short (recommend max 24 chars), this information is displayed in the centre of the demo description card |
+| emoji | Do not update this, our demos will use a consistent emoji character |
+| colorFrom | Do not update this, used in combination with colorTo to colourize the demo description card |
+| colorTo | see colorFrom |
+| sdk | Do not update this, our Gradio demos will always use the "gradio" setting |
+| sdk_version | Update this if necessary for your demo to function, ideally should be set to the latest gradio version |
+| app_file | Update this if necessary for your demo to function, should be set to the path of the main entry point to the demo |
+| license | Do not update this, our demos are to always be apache-2.0 licensed |
+| short_description | **Update this**, should be set to a few words that describe the demo in a little more detail than the title, this information is displayed in the bottom-right of the demo description card |
+
+Other available options:
+| Setting | Notes |
+| ------- | ----- |
+| python_version | You may optionally set this, best advice is to use the default Python version if possible (current default is Python 3.10) |
+| suggested_hardware | Do not use this, unlikely to be required as demos run on ZeroGPU |
+| suggested_storage | Do not use this, our demos do not require storage |
+| app_port | Do not use this, not relevant for gradio demos |
+| base_path | Do not use this, use the app_file setting |
+| fullWidth | Do not use this, our demos will use a consistent default width |
+| header | Do not use this, our demos will use a consistent header |
+| models | Do not use this, let their parsing discover these from our code |
+| datasets | Do not use this, let their parsing discover these from our code |
+| tags | Do not use this, we are not tagging our demos |
+| thumbnail | Do not use this, provides a thumbnail for social sharing of demos |
+| pinned | Do not use this, the RDTE team will change this setting if it's deemed necessary |
+| hf_oauth | Do not use this, we are not using OAuth |
+| hf_oauth_scopes | Do not use this, we are not using OAuth |
+| hf_oauth_expiration_minutes | Do not use this, we are not using OAuth |
+| disable_embedding | Do not use this, leave at the default that allows embedding to take place |
+| startup_duration_timeout | Do not use this, leave at the default 30 minutes |
+| custom_headers | Do not use this, we do not need to add any custom HTTP headers |
+| preload_from_hub | Do not use this, specifying this builds the models and data sets into the container image with the goal of making start up times faster due to not needing to download them each time. However, RDTE testing indicates this setting significantly increases the start up time for our relatively small Granite models |

README.md

@@ -0,0 +1,11 @@
+---
+title: Granite Vision Document Intelligence
+short_description: Document intelligence with Granite-Vision-4.1-4B
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 5.16.1
+app_file: src/app.py
+pinned: False
+license: apache-2.0
+---

pyproject.toml

@@ -0,0 +1,66 @@
+[tool.poetry]
+name = "granite-vision-document-intelligence"
+version = "0.1.0"
+description = "Document intelligence demo powered by IBM Granite Vision and Docling"
+authors = ["Pengyuan Li <pengyuan@ibm.com>"]
+license = "Apache-2.0"
+readme = "README.md"
+package-mode = false
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.11"
+gradio = "5.9.1"
+torch = "2.4.0"
+spaces = "0.30.4"
+transformers = "^4.47.1"
+accelerate = "^1.2.1"
+PyMuPDF = ">=1.24.0"
+Pillow = ">=10.0.0"
+python-dotenv = "^1.0.0"
+pandas = ">=2.0.0"
+numpy = ">=1.24.0"
+requests = ">=2.31.0"
+tqdm = ">=4.66.0"
+docling = ">=1.18.0"
+docling-core = ">=2.5.0"
+
+
+[tool.poetry.group.dev.dependencies]
+pre-commit = "^4.0.1"
+git-lint = "^0.1.2"
+ruff = "^0.8.3"
+pytest = "^8.3.4"
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.ruff]
+select = [
+    "E",   # pycodestyle
+    "F",   # pyflakes
+    "UP",  # pyupgrade
+    "D",   # pydocstyle
+    "I",   # isort
+    "B",   # bugbear
+    "ANN", # annotations
+    "N",   # pep8-naming
+    "C4",  # Comprehensions
+    "DTZ", # DatetimeZ
+    "Q",   # Quotes
+    "SIM", # Simplify
+    "RUF", # Ruff
+]
+ignore = ["D203", "D213"]
+fixable = ["ALL"]
+unfixable = []
+line-length = 120
+
+
+[tool.black]
+line-length = 120
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

requirements.txt

@@ -0,0 +1,14 @@
+gradio==5.16.1
+transformers>=5.6.2
+torch>=2.5.0
+accelerate>=1.2.1,<2.0.0
+peft>=0.7.0
+Pillow>=10.0.0
+PyMuPDF>=1.24.0
+python-dotenv>=1.0.0,<2.0.0
+pandas>=2.0.0
+numpy>=1.24.0
+requests>=2.31.0
+tqdm>=4.66.0
+docling>=1.18.0
+docling-core>=2.5.0

src/app.css

@@ -0,0 +1,8 @@
+footer {
+    display: none !important;
+}
+
+.figure-image .image-container {
+    margin-left: 12px;
+    margin-right: 12px;
+}

src/app.py

@@ -0,0 +1,550 @@
+"""Granite Vision Document Intelligence Demo.
+
+Upload a PDF or image to explore Granite-Vision-4.1-4B capabilities including
+Chart2CSV, Chart2Code, Chart2Summary, Table Extraction, and Image Q&A.
+"""
+
+# Monkey-patch gradio_client to handle bool JSON Schema values.
+# gradio 5.x emits additionalProperties: false/true (valid JSON Schema)
+# but gradio_client 1.5.x does not guard against bool in get_type(),
+# causing TypeError on every request to the /info endpoint.
+try:
+    import gradio_client.utils as _gcu
+
+    _orig_get_type = _gcu.get_type
+    _orig_j2p = _gcu._json_schema_to_python_type
+
+    def _patched_get_type(schema):  # noqa: ANN001, ANN202
+        if not isinstance(schema, dict):
+            return "unknown"
+        return _orig_get_type(schema)
+
+    def _patched_j2p(schema, defs=None):  # noqa: ANN001, ANN202
+        if not isinstance(schema, dict):
+            return "any" if schema else "unknown"
+        return _orig_j2p(schema, defs)
+
+    _gcu.get_type = _patched_get_type
+    _gcu._json_schema_to_python_type = _patched_j2p
+except Exception:  # noqa: BLE001
+    pass
+
+import os
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+from PIL import Image
+
+from crops import extract_figures
+from document_parser import parse_document
+from infer_chart2csv import extract_csv_stream
+from infer_vision_qa import answer_question_stream
+from model_loader import load_processor
+from pdf_io import load_pdf_pages
+from themes.research_monochrome import theme
+from ui_state import create_initial_state, hash_bytes, page_cache, parse_cache
+
+# Pre-load the processor at startup (CPU-only, no GPU needed).
+# This avoids paying the processor load cost on the first user request.
+load_processor()
+
+TITLE = "Granite Vision: Document Intelligence"
+DESCRIPTION = (
+    "Upload a PDF, Word, Excel, PowerPoint, or image to explore Granite-Vision-4.1-4B's document intelligence capabilities — "
+    "including Chart2Summary, Chart2CSV, Chart2Code, Table Extraction, and Image Description — "
+    "with automatic Docling-powered parsing for documents and direct inference on uploaded images."
+)
+
+IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".jfif", ".png", ".bmp", ".dib", ".gif", ".tif", ".tiff", ".webp"}
+OFFICE_EXTENSIONS = {".docx", ".xlsx", ".pptx"}
+
+css_file_path = Path(Path(__file__).parent / "app.css")
+head_file_path = Path(Path(__file__).parent / "app_head.html")
+
+
+def _is_image_file(file_path: str) -> bool:
+    """Check whether a file path points to a supported image format."""
+    ext = os.path.splitext(file_path)[1].lower()
+    return ext in IMAGE_EXTENSIONS
+
+
+def _is_office_file(file_path: str) -> bool:
+    """Check whether a file path points to a supported Office format (DOCX/XLSX/PPTX)."""
+    ext = os.path.splitext(file_path)[1].lower()
+    return ext in OFFICE_EXTENSIONS
+
+
+def process_upload(file_path: str, session_state: dict[str, Any]) -> tuple:
+    """Parse an uploaded PDF or load an image and extract figures.
+
+    Args:
+        file_path: Path to the uploaded file.
+        session_state: Current Gradio session state dictionary.
+
+    Returns:
+        Tuple of (status, html_content, fig_status, fig_caption, fig_image, session_state).
+    """
+    max_pages = 20
+
+    session_state["current_figure_index"] = 0
+    session_state["conversation_history"] = []
+    session_state["current_image_path"] = None
+
+    if not file_path:
+        return "Please upload a PDF, Office document, or image.", "No document loaded", "No figures", "", None, session_state
+
+    try:
+        with open(file_path, "rb") as f:
+            file_bytes = f.read()
+
+        file_hash = hash_bytes(file_bytes)
+        session_state["uploaded_file_hash"] = file_hash
+        session_state["uploaded_file_bytes"] = file_bytes
+
+        if _is_image_file(file_path):
+            image = Image.open(file_path).convert("RGB")
+            figures_info = [{"image": image, "page": 0, "bbox": None, "caption": ""}]
+
+            session_state["page_images"] = [image]
+            session_state["parsed_result"] = {}
+            session_state["figures_info"] = figures_info
+            session_state["selected_figure"] = figures_info[0]
+
+            return (
+                "Image loaded successfully.\nNumber of figures: 1.",
+                "Image uploaded directly (no document parsing needed)",
+                "Figure 1 of 1 (Page 1)",
+                "",
+                image,
+                session_state,
+            )
+
+        file_ext = os.path.splitext(file_path)[1].lower()
+        is_office = _is_office_file(file_path)
+        fmt_label = file_ext.lstrip(".").upper()
+        status_lines = [f"{fmt_label} loaded successfully."]
+
+        if is_office:
+            page_images = []
+            session_state["page_images"] = []
+        else:
+            cache_key = f"{file_hash}_{max_pages}"
+            if cache_key in page_cache:
+                page_images = page_cache[cache_key]
+            else:
+                page_images = load_pdf_pages(file_bytes, max_pages=max_pages)
+                page_cache[cache_key] = page_images
+            session_state["page_images"] = page_images
+            status_lines.append(f"Number of pages rendered: {len(page_images)} (max {max_pages}).")
+
+        if file_hash in parse_cache:
+            parse_result = parse_cache[file_hash]
+        else:
+            parse_result = parse_document(file_bytes, file_ext=file_ext)
+            parse_cache[file_hash] = parse_result
+        session_state["parsed_result"] = parse_result
+        status_lines.append("Document parsing done using Docling.")
+
+        figures_info = extract_figures(page_images, parse_result.get("figures", []))
+        session_state["figures_info"] = figures_info
+        status_lines.append(f"Number of figures extracted: {len(figures_info)}.")
+
+        if figures_info:
+            session_state["selected_figure"] = figures_info[0]
+            fig_status = f"Figure 1 of {len(figures_info)} (Page {figures_info[0]['page'] + 1})"
+            fig_caption = figures_info[0].get("caption", "No caption")
+            fig_image = figures_info[0]["image"]
+        else:
+            session_state["selected_figure"] = None
+            fig_status = "No figures found"
+            fig_caption = ""
+            fig_image = None
+
+        html_content = parse_result.get("html", "No content available")
+        status = "\n".join(status_lines)
+
+        return status, html_content, fig_status, fig_caption, fig_image, session_state
+
+    except Exception as e:  # noqa: BLE001
+        import traceback
+
+        print(f"Error: {e}")
+        traceback.print_exc()
+        return f"Error: {e!s}", f"Error loading document: {e!s}", "Error", "", None, session_state
+
+
+def _get_figure_display(session_state: dict[str, Any]) -> tuple[str, str, Image.Image | None]:
+    """Return the current figure's display info, caption, and image.
+
+    Args:
+        session_state: Current session state dictionary.
+
+    Returns:
+        Tuple of (fig_status, fig_caption, fig_image).
+    """
+    figures_info = session_state.get("figures_info", [])
+    idx = session_state.get("current_figure_index", 0)
+
+    if not figures_info:
+        return "No figures found", "", None
+
+    fig = figures_info[idx]
+    fig_status = f"Figure {idx + 1} of {len(figures_info)} (Page {fig['page'] + 1})"
+    fig_caption = fig.get("caption", "No caption")
+    return fig_status, fig_caption, fig["image"]
+
+
+def next_figure(session_state: dict[str, Any]) -> tuple:
+    """Advance to the next figure.
+
+    Args:
+        session_state: Current session state dictionary.
+
+    Returns:
+        Tuple of (fig_status, fig_caption, fig_image, session_state).
+    """
+    figures_info = session_state.get("figures_info", [])
+
+    if not figures_info:
+        return "No figures found", "", None, session_state
+
+    idx = (session_state.get("current_figure_index", 0) + 1) % len(figures_info)
+    session_state["current_figure_index"] = idx
+    session_state["selected_figure"] = figures_info[idx]
+    session_state["conversation_history"] = []
+    session_state["current_image_path"] = None
+
+    fig_status, fig_caption, fig_image = _get_figure_display(session_state)
+    return fig_status, fig_caption, fig_image, session_state
+
+
+def prev_figure(session_state: dict[str, Any]) -> tuple:
+    """Go back to the previous figure.
+
+    Args:
+        session_state: Current session state dictionary.
+
+    Returns:
+        Tuple of (fig_status, fig_caption, fig_image, session_state).
+    """
+    figures_info = session_state.get("figures_info", [])
+
+    if not figures_info:
+        return "No figures found", "", None, session_state
+
+    idx = (session_state.get("current_figure_index", 0) - 1) % len(figures_info)
+    session_state["current_figure_index"] = idx
+    session_state["selected_figure"] = figures_info[idx]
+    session_state["conversation_history"] = []
+    session_state["current_image_path"] = None
+
+    fig_status, fig_caption, fig_image = _get_figure_display(session_state)
+    return fig_status, fig_caption, fig_image, session_state
+
+
+def describe_image_helper(session_state: dict[str, Any]):  # noqa: ANN201
+    """Generate a detailed description of the selected figure (streaming)."""
+    selected_fig = session_state.get("selected_figure")
+    if selected_fig is None:
+        yield "No figure selected", session_state
+        return
+    try:
+        image = selected_fig["image"]
+        for partial in answer_question_stream(image, "Describe this image in detail", [], None):
+            yield partial, session_state
+    except Exception as e:  # noqa: BLE001
+        yield f"Error: {e!s}", session_state
+
+
+def load_current_figure(session_state: dict[str, Any]) -> tuple:
+    """Load the current figure into display components (called on tab select).
+
+    Also clears conversation history so each tab starts fresh.
+    """
+    session_state["conversation_history"] = []
+    session_state["current_image_path"] = None
+    fig_status, fig_caption, fig_image = _get_figure_display(session_state)
+    return fig_status, fig_caption, fig_image, session_state
+
+
+PROMPT_TEXT_CODE = (
+    "Please take a look at this chart image and generate Python code that perfectly reconstructs this chart image."
+)
+
+PROMPT_TEXT_SUMMARY = "<chart2summary>"
+
+PROMPT_TEXT_TABLE = "<tables_html>"
+
+
+def extract_code_helper(session_state: dict[str, Any]):  # noqa: ANN201
+    """Generate Python code to reconstruct the selected chart (streaming)."""
+    selected_fig = session_state.get("selected_figure")
+    if selected_fig is None:
+        yield "No figure selected", session_state
+        return
+    try:
+        image = selected_fig["image"]
+        for partial in answer_question_stream(image, PROMPT_TEXT_CODE, [], None):
+            yield partial, session_state
+    except Exception as e:  # noqa: BLE001
+        yield f"Error: {e!s}", session_state
+
+
+def extract_summary_helper(session_state: dict[str, Any]):  # noqa: ANN201
+    """Generate a text summary of the selected chart (streaming)."""
+    selected_fig = session_state.get("selected_figure")
+    if selected_fig is None:
+        yield "No figure selected", session_state
+        return
+    try:
+        image = selected_fig["image"]
+        for partial in answer_question_stream(image, PROMPT_TEXT_SUMMARY, [], None):
+            yield partial, session_state
+    except Exception as e:  # noqa: BLE001
+        yield f"Error: {e!s}", session_state
+
+
+def extract_table_helper(session_state: dict[str, Any]):  # noqa: ANN201
+    """Extract tables as HTML from the selected figure (streaming)."""
+    import re
+    selected_fig = session_state.get("selected_figure")
+    if selected_fig is None:
+        yield "No figure selected", session_state
+        return
+    try:
+        image = selected_fig["image"]
+        accumulated = ""
+        for partial in answer_question_stream(image, PROMPT_TEXT_TABLE, [], None):
+            accumulated = partial
+            yield accumulated, session_state
+        # Final pass: strip markdown fences / brackets the model may wrap around HTML
+        cleaned = re.sub(r"^```(?:html)?\s*", "", accumulated.strip())
+        cleaned = re.sub(r"\s*```$", "", cleaned.strip())
+        cleaned = re.sub(r"^\[\s*", "", cleaned.strip())
+        cleaned = re.sub(r"\s*\]$", "", cleaned.strip())
+        if cleaned != accumulated:
+            yield cleaned, session_state
+    except Exception as e:  # noqa: BLE001
+        yield f"Error: {e!s}", session_state
+
+
+def extract_csv_helper(session_state: dict[str, Any]):  # noqa: ANN201
+    """Extract CSV data from the selected chart (streaming)."""
+    selected_fig = session_state.get("selected_figure")
+    if selected_fig is None:
+        yield "No figure selected", session_state
+        return
+    try:
+        image = selected_fig["image"]
+        for partial in extract_csv_stream(image):
+            yield partial, session_state
+    except Exception as e:  # noqa: BLE001
+        yield f"Error: {e!s}", session_state
+
+
+def _make_nav(nav_fn: Any) -> Any:
+    """Wrap a nav function to also clear the result panel when navigating figures."""
+    def _wrapper(session_state: dict[str, Any]) -> tuple:
+        fig_status, fig_caption, fig_image, state = nav_fn(session_state)
+        return fig_status, fig_caption, fig_image, "", state
+    return _wrapper
+
+
+with gr.Blocks(
+    title=TITLE,
+    theme=theme,
+    css_paths=css_file_path,
+    head_paths=head_file_path,
+    fill_height=True,
+) as demo:
+    gr.Markdown(f"# {TITLE}")
+    gr.Markdown(DESCRIPTION)
+
+    session_state = gr.State(create_initial_state())
+
+    # Per-tab nav wrappers: clear result output when switching figures
+    _sum_prev  = _make_nav(prev_figure)
+    _sum_next  = _make_nav(next_figure)
+    _csv_prev  = _make_nav(prev_figure)
+    _csv_next  = _make_nav(next_figure)
+    _code_prev = _make_nav(prev_figure)
+    _code_next = _make_nav(next_figure)
+    _tbl_prev  = _make_nav(prev_figure)
+    _tbl_next  = _make_nav(next_figure)
+    _qa_prev   = _make_nav(prev_figure)
+    _qa_next   = _make_nav(next_figure)
+
+    with gr.Tabs():
+        # TAB 1: UPLOAD & PARSE
+        with gr.Tab("Parse & Extract"):
+            file_path = gr.File(
+                label="Upload PDF, Office Document, or Image",
+                file_types=[".pdf", ".docx", ".xlsx", ".pptx", ".jpg", ".jpeg", ".jfif", ".png", ".bmp", ".dib", ".gif", ".tif", ".tiff", ".webp"],
+            )
+
+            status = gr.Textbox(label="Status", interactive=False, lines=2)
+
+            with gr.Row():
+                with gr.Column(scale=1):
+                    html_view = gr.Textbox(
+                        label="Parsed Document (Docling)",
+                        value="Upload a document to see parsed content",
+                        lines=35,
+                        interactive=False,
+                    )
+
+                with gr.Column(scale=1):
+                    gr.Markdown("### Extracted Figures")
+                    fig_info = gr.Textbox(label="Figure Info", interactive=False)
+                    fig_caption = gr.Textbox(label="Caption", interactive=False)
+                    fig_image = gr.Image(label="Figure", type="pil", elem_classes=["figure-image"])
+
+                    with gr.Row():
+                        prev_btn = gr.Button("Previous", scale=1)
+                        next_btn = gr.Button("Next", scale=1)
+
+            file_path.upload(
+                process_upload,
+                inputs=[file_path, session_state],
+                outputs=[status, html_view, fig_info, fig_caption, fig_image, session_state],
+            )
+            next_btn.click(
+                next_figure,
+                inputs=[session_state],
+                outputs=[fig_info, fig_caption, fig_image, session_state],
+            )
+            prev_btn.click(
+                prev_figure,
+                inputs=[session_state],
+                outputs=[fig_info, fig_caption, fig_image, session_state],
+            )
+
+        # TAB 2: CHART2SUMMARY
+        with gr.Tab("Chart2Summary") as summary_tab:
+            gr.Markdown("Generate a text summary of the selected chart")
+
+            with gr.Row():
+                with gr.Column(scale=1):
+                    gr.Markdown("### Figure")
+                    summary_fig_info = gr.Textbox(label="Figure Info", interactive=False)
+                    summary_fig_caption = gr.Textbox(label="Caption", interactive=False)
+                    summary_fig_image = gr.Image(label="Figure", type="pil", elem_classes=["figure-image"])
+
+                    with gr.Row():
+                        summary_prev_btn = gr.Button("Previous", scale=1)
+                        summary_next_btn = gr.Button("Next", scale=1)
+
+                with gr.Column(scale=1):
+                    gr.Markdown("### Summary")
+                    summary_btn = gr.Button("Generate Summary", variant="primary")
+                    summary_out = gr.Textbox(label="Chart Summary", lines=20, interactive=False)
+
+            summary_prev_btn.click(_sum_prev, inputs=[session_state], outputs=[summary_fig_info, summary_fig_caption, summary_fig_image, summary_out, session_state])
+            summary_next_btn.click(_sum_next, inputs=[session_state], outputs=[summary_fig_info, summary_fig_caption, summary_fig_image, summary_out, session_state])
+            summary_btn.click(extract_summary_helper, inputs=[session_state], outputs=[summary_out, session_state])
+            summary_tab.select(load_current_figure, inputs=[session_state], outputs=[summary_fig_info, summary_fig_caption, summary_fig_image, session_state])
+
+        # TAB 3: CHART2CSV
+        with gr.Tab("Chart2CSV") as csv_tab:
+            gr.Markdown("Extract CSV data from the selected chart")
+
+            with gr.Row():
+                with gr.Column(scale=1):
+                    gr.Markdown("### Figure")
+                    csv_fig_info = gr.Textbox(label="Figure Info", interactive=False)
+                    csv_fig_caption = gr.Textbox(label="Caption", interactive=False)
+                    csv_fig_image = gr.Image(label="Figure", type="pil", elem_classes=["figure-image"])
+
+                    with gr.Row():
+                        csv_prev_btn = gr.Button("Previous", scale=1)
+                        csv_next_btn = gr.Button("Next", scale=1)
+
+                with gr.Column(scale=1):
+                    gr.Markdown("### CSV Extraction")
+                    extract_btn = gr.Button("Extract CSV", variant="primary")
+                    csv_out = gr.Textbox(label="CSV", lines=20, interactive=False)
+
+            csv_prev_btn.click(_csv_prev, inputs=[session_state], outputs=[csv_fig_info, csv_fig_caption, csv_fig_image, csv_out, session_state])
+            csv_next_btn.click(_csv_next, inputs=[session_state], outputs=[csv_fig_info, csv_fig_caption, csv_fig_image, csv_out, session_state])
+            extract_btn.click(extract_csv_helper, inputs=[session_state], outputs=[csv_out, session_state])
+            csv_tab.select(load_current_figure, inputs=[session_state], outputs=[csv_fig_info, csv_fig_caption, csv_fig_image, session_state])
+
+        # TAB 4: CHART2CODE
+        with gr.Tab("Chart2Code") as code_tab:
+            gr.Markdown("Generate Python code to reconstruct the selected chart")
+
+            with gr.Row():
+                with gr.Column(scale=1):
+                    gr.Markdown("### Figure")
+                    code_fig_info = gr.Textbox(label="Figure Info", interactive=False)
+                    code_fig_caption = gr.Textbox(label="Caption", interactive=False)
+                    code_fig_image = gr.Image(label="Figure", type="pil", elem_classes=["figure-image"])
+
+                    with gr.Row():
+                        code_prev_btn = gr.Button("Previous", scale=1)
+                        code_next_btn = gr.Button("Next", scale=1)
+
+                with gr.Column(scale=1):
+                    gr.Markdown("### Generated Code")
+                    code_btn = gr.Button("Generate Code", variant="primary")
+                    code_out = gr.Textbox(label="Python Code", lines=20, interactive=False)
+
+            code_prev_btn.click(_code_prev, inputs=[session_state], outputs=[code_fig_info, code_fig_caption, code_fig_image, code_out, session_state])
+            code_next_btn.click(_code_next, inputs=[session_state], outputs=[code_fig_info, code_fig_caption, code_fig_image, code_out, session_state])
+            code_btn.click(extract_code_helper, inputs=[session_state], outputs=[code_out, session_state])
+            code_tab.select(load_current_figure, inputs=[session_state], outputs=[code_fig_info, code_fig_caption, code_fig_image, session_state])
+
+        # TAB 5: TABLE EXTRACTION
+        with gr.Tab("Table Extraction") as table_tab:
+            gr.Markdown("Extract table data as HTML from the selected figure")
+
+            with gr.Row():
+                with gr.Column(scale=1):
+                    gr.Markdown("### Figure")
+                    table_fig_info = gr.Textbox(label="Figure Info", interactive=False)
+                    table_fig_caption = gr.Textbox(label="Caption", interactive=False)
+                    table_fig_image = gr.Image(label="Figure", type="pil", elem_classes=["figure-image"])
+
+                    with gr.Row():
+                        table_prev_btn = gr.Button("Previous", scale=1)
+                        table_next_btn = gr.Button("Next", scale=1)
+
+                with gr.Column(scale=1):
+                    gr.Markdown("### Table Extraction")
+                    table_btn = gr.Button("Extract Table", variant="primary")
+                    table_out = gr.HTML(value="<p>Upload a document and click Extract Table to see results here</p>")
+
+            table_prev_btn.click(_tbl_prev, inputs=[session_state], outputs=[table_fig_info, table_fig_caption, table_fig_image, table_out, session_state])
+            table_next_btn.click(_tbl_next, inputs=[session_state], outputs=[table_fig_info, table_fig_caption, table_fig_image, table_out, session_state])
+            table_btn.click(extract_table_helper, inputs=[session_state], outputs=[table_out, session_state])
+            table_tab.select(load_current_figure, inputs=[session_state], outputs=[table_fig_info, table_fig_caption, table_fig_image, session_state])
+
+        # TAB 6: IMAGE DESCRIPTION
+        with gr.Tab("Image Description") as qa_tab:
+            gr.Markdown("Get a detailed description of the selected figure")
+
+            with gr.Row():
+                with gr.Column(scale=1):
+                    gr.Markdown("### Figure")
+                    qa_fig_info = gr.Textbox(label="Figure Info", interactive=False)
+                    qa_fig_caption = gr.Textbox(label="Caption", interactive=False)
+                    qa_fig_image = gr.Image(label="Figure", type="pil", elem_classes=["figure-image"])
+
+                    with gr.Row():
+                        qa_prev_btn = gr.Button("Previous", scale=1)
+                        qa_next_btn = gr.Button("Next", scale=1)
+
+                with gr.Column(scale=1):
+                    gr.Markdown("### Description")
+                    describe_btn = gr.Button("Describe Image", variant="primary")
+                    answer = gr.Textbox(label="Description", lines=20, interactive=False)
+
+            qa_prev_btn.click(_qa_prev, inputs=[session_state], outputs=[qa_fig_info, qa_fig_caption, qa_fig_image, answer, session_state])
+            qa_next_btn.click(_qa_next, inputs=[session_state], outputs=[qa_fig_info, qa_fig_caption, qa_fig_image, answer, session_state])
+            describe_btn.click(describe_image_helper, inputs=[session_state], outputs=[answer, session_state])
+            qa_tab.select(load_current_figure, inputs=[session_state], outputs=[qa_fig_info, qa_fig_caption, qa_fig_image, session_state])
+
+
+if __name__ == "__main__":
+    demo.launch(ssr_mode=False)

src/app_head.html

@@ -0,0 +1,12 @@
+<script
+  async
+  src="https://www.googletagmanager.com/gtag/js?id=G-C6LFT227RC"
+></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag() {
+    dataLayer.push(arguments);
+  }
+  gtag("js", new Date());
+  gtag("config", "G-C6LFT227RC");
+</script>

src/crops.py

@@ -0,0 +1,71 @@
+"""Figure extraction and processing using PIL images from Docling."""
+
+from typing import Any
+
+from PIL import Image
+
+
+def extract_figures(
+    page_images: list[Image.Image],
+    figures_info: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    """Process figures extracted by Docling into a consistent format.
+
+    Docling extracts figure images directly. This function validates them,
+    creates thumbnails, and falls back to page previews when no figures exist.
+
+    Args:
+        page_images: List of rendered page images (used as fallback only).
+        figures_info: List of figure metadata dicts from Docling, each containing
+            ``image``, ``bbox``, ``page``, and ``caption`` fields.
+
+    Returns:
+        List of dicts with ``image`` (PIL), ``thumbnail``, ``bbox``, ``page``, and ``caption``.
+    """
+    results: list[dict[str, Any]] = []
+
+    try:
+        for fig_info in figures_info:
+            pil_image = fig_info.get("image")
+
+            if pil_image is None:
+                print(f"Figure missing image: {fig_info}")
+                continue
+
+            if not isinstance(pil_image, Image.Image):
+                print(f"Figure image is not PIL Image: {type(pil_image)}")
+                continue
+
+            thumb = pil_image.copy()
+            thumb.thumbnail((200, 200), Image.Resampling.LANCZOS)
+
+            results.append({
+                "image": pil_image,
+                "thumbnail": thumb,
+                "bbox": fig_info.get("bbox"),
+                "page": fig_info.get("page", 0),
+                "caption": fig_info.get("caption", ""),
+            })
+
+            print(f"Processed figure {len(results)}")
+
+    except Exception as e:  # noqa: BLE001
+        import traceback
+
+        print(f"Error processing figures: {e}")
+        traceback.print_exc()
+
+    if not results and page_images:
+        print("No figures extracted, using page previews as fallback")
+        for i, page_img in enumerate(page_images[:3]):
+            thumb = page_img.copy()
+            thumb.thumbnail((200, 200), Image.Resampling.LANCZOS)
+            results.append({
+                "image": page_img,
+                "thumbnail": thumb,
+                "bbox": None,
+                "page": i,
+                "caption": f"Page {i + 1}",
+            })
+
+    return results

src/document_parser.py

@@ -0,0 +1,146 @@
+"""Docling document parsing with figure extraction and markdown export."""
+
+import os
+import tempfile
+from collections.abc import Callable
+from typing import Any
+
+
+_EXT_TO_INPUT_FORMAT = {
+    ".pdf": "PDF",
+    ".docx": "DOCX",
+    ".xlsx": "XLSX",
+    ".pptx": "PPTX",
+}
+
+
+def parse_document(
+    file_bytes: bytes,
+    file_ext: str = ".pdf",
+    on_progress: Callable[[str], None] | None = None,
+) -> dict[str, Any]:
+    """Parse a document with Docling and extract markdown, text, and figure regions.
+
+    Args:
+        file_bytes: Document file content as bytes.
+        file_ext: File extension (e.g. ``".pdf"``, ``".docx"``, ``".xlsx"``, ``".pptx"``).
+        on_progress: Optional callback ``(phase_message) -> None`` for progress reporting.
+
+    Returns:
+        Dictionary with keys:
+            - ``html``: HTML-wrapped markdown representation of the document.
+            - ``text``: Full extracted plain text.
+            - ``figures``: List of figure dicts with ``bbox``, ``page``, ``caption``, and ``image``.
+    """
+    def _report(msg: str) -> None:
+        if on_progress:
+            on_progress(msg)
+
+    try:
+        from docling.datamodel.base_models import InputFormat
+        from docling.document_converter import DocumentConverter, PdfFormatOption
+
+        ext = file_ext.lower()
+        with tempfile.NamedTemporaryFile(suffix=ext, delete=False) as tmp:
+            tmp.write(file_bytes)
+            tmp_path = tmp.name
+
+        try:
+            format_name = _EXT_TO_INPUT_FORMAT.get(ext, "PDF")
+            input_format = getattr(InputFormat, format_name)
+
+            _report("Initializing document converter...")
+
+            if input_format == InputFormat.PDF:
+                pdf_format_option = PdfFormatOption()
+                pdf_format_option.pipeline_options.generate_picture_images = True
+                pdf_format_option.pipeline_options.images_scale = 2.0
+
+                # Force CPU to avoid CUDA init outside @spaces.GPU on ZeroGPU spaces
+                try:
+                    from docling.datamodel.pipeline_options import AcceleratorDevice, AcceleratorOptions
+                    pdf_format_option.pipeline_options.accelerator_options = AcceleratorOptions(
+                        device=AcceleratorDevice.CPU
+                    )
+                except Exception:  # noqa: BLE001
+                    pass  # Older docling versions without AcceleratorOptions
+
+                converter = DocumentConverter(format_options={InputFormat.PDF: pdf_format_option})
+            else:
+                converter = DocumentConverter()
+
+            _report("Converting document (this may take a moment)...")
+            result = converter.convert(tmp_path)
+            doc = result.document
+
+            _report("Exporting document content...")
+            markdown_text = doc.export_to_markdown()
+            html = markdown_text
+            text = doc.export_to_text()
+
+            _report("Processing figures...")
+            figures: list[dict[str, Any]] = []
+            try:
+                if hasattr(doc, "pictures"):
+                    for figure in doc.pictures:
+                        if figure.content_layer.value != "body":
+                            continue
+
+                        page_num = 0
+                        bbox_list = None
+
+                        if figure.prov:
+                            page_num = figure.prov[0].page_no - 1  # Docling is 1-based
+                            bbox = figure.prov[0].bbox
+                            bbox_list = [bbox.l, bbox.t, bbox.width, bbox.height]
+
+                        caption = ""
+                        if figure.captions:
+                            for cap_ref in figure.captions:
+                                try:
+                                    if hasattr(cap_ref, "cref") and cap_ref.cref.startswith("#/texts/"):
+                                        idx = int(cap_ref.cref.split("/")[-1])
+                                        if idx < len(doc.texts):
+                                            caption = doc.texts[idx].text
+                                            break
+                                except Exception:  # noqa: BLE001
+                                    pass
+
+                        if figure.image:
+                            try:
+                                pil_image = figure.image.pil_image
+                                figures.append({
+                                    "bbox": bbox_list,
+                                    "page": page_num,
+                                    "caption": caption,
+                                    "image": pil_image,
+                                })
+                            except Exception:  # noqa: BLE001
+                                pass
+
+            except Exception:  # noqa: BLE001
+                figures = []
+
+            return {"html": html, "text": text, "figures": figures}
+
+        finally:
+            if os.path.exists(tmp_path):
+                os.unlink(tmp_path)
+
+    except ImportError as e:
+        print(f"Docling import error: {e}, using placeholder")
+        return {
+            "html": "<h1>Sample Document</h1><p>Docling not available - using placeholder.</p>",
+            "text": "Sample text from PDF.\n\nDocling not available - using placeholder.",
+            "figures": [],
+        }
+    except Exception as e:  # noqa: BLE001
+        import traceback
+
+        print(f"Docling parse error: {e}")
+        traceback.print_exc()
+        return {
+            "html": f"<h1>Error</h1><pre>{e!s}</pre>",
+            "text": f"Error: {e!s}",
+            "figures": [],
+        }

src/infer_chart2csv.py

@@ -0,0 +1,106 @@
+"""Chart-to-CSV extraction using Granite Vision.
+
+Converts chart images to tabular CSV data using ibm-granite/granite-vision-4.1-4b.
+
+Same ZeroGPU streaming pattern as infer_vision_qa.py — see that module for details.
+"""
+
+import threading
+from collections.abc import Generator
+
+import spaces
+import torch
+from PIL import Image
+from transformers import TextIteratorStreamer
+
+from model_loader import load_model, load_processor
+
+
+@spaces.GPU(duration=120)
+def extract_csv_stream(image: Image.Image) -> Generator[str, None, None]:
+    """Stream CSV extraction token-by-token from a chart image.
+
+    Runs inside @spaces.GPU. model.generate() runs in a plain background thread.
+
+    Args:
+        image: PIL Image of a chart or table.
+
+    Yields:
+        Accumulated CSV text after each token.
+    """
+    processor, model = load_model()
+
+    if processor is None or model is None:
+        yield "col1,col2,col3\nvalue1,value2,value3\nvalue4,value5,value6"
+        return
+
+    try:
+        image = image.convert("RGB")
+        conversation = [{"role": "user", "content": [
+            {"type": "image"},
+            {"type": "text", "text": "<chart2csv>"},
+        ]}]
+        text = processor.apply_chat_template(conversation, tokenize=False, add_generation_prompt=True)
+        inputs = processor(text=text, images=image, return_tensors="pt").to(model.device)
+
+        streamer = TextIteratorStreamer(processor.tokenizer, skip_prompt=True, skip_special_tokens=True)
+
+        def _generate() -> None:
+            with torch.inference_mode():
+                model.generate(**inputs, max_new_tokens=4096, use_cache=True, streamer=streamer)
+
+        thread = threading.Thread(target=_generate)
+        thread.start()
+
+        accumulated = ""
+        for token in streamer:
+            if token:
+                accumulated += token
+                yield accumulated
+
+        thread.join()
+
+    except Exception as e:  # noqa: BLE001
+        import traceback
+        traceback.print_exc()
+        yield f"Error: {e!s}"
+
+
+@spaces.GPU(duration=120)
+def extract_csv(image: Image.Image) -> str:
+    """Extract CSV data from a chart image using Granite Vision (non-streaming).
+
+    Args:
+        image: PIL Image of a chart or table.
+
+    Returns:
+        CSV-formatted text extracted from the chart.
+    """
+    processor, model = load_model()
+
+    if processor is None or model is None:
+        return "col1,col2,col3\nvalue1,value2,value3\nvalue4,value5,value6"
+
+    try:
+        image = image.convert("RGB")
+        conversation = [{"role": "user", "content": [
+            {"type": "image"},
+            {"type": "text", "text": "<chart2csv>"},
+        ]}]
+        text = processor.apply_chat_template(conversation, tokenize=False, add_generation_prompt=True)
+        inputs = processor(text=text, images=image, return_tensors="pt").to(model.device)
+
+        max_new_tokens = 4096
+        with torch.inference_mode():
+            outputs = model.generate(**inputs, max_new_tokens=max_new_tokens, use_cache=True)
+
+        gen = outputs[0, inputs["input_ids"].shape[1]:]
+        result = processor.decode(gen, skip_special_tokens=True)
+        if len(gen) >= max_new_tokens:
+            result += "\n\n[Max token limit reached — response may be truncated]"
+        return result
+
+    except Exception as e:  # noqa: BLE001
+        import traceback
+        traceback.print_exc()
+        return f"Error: {e!s}"

src/infer_vision_qa.py

@@ -0,0 +1,155 @@
+"""Granite Vision image and chart Q&A.
+
+Supports single-turn and multi-turn conversations using ibm-granite/granite-vision-4.1-4b.
+
+ZeroGPU streaming pattern:
+- answer_question_stream is decorated with @spaces.GPU so the entire generator
+  runs inside the ZeroGPU subprocess with GPU access.
+- model.generate() is called in a plain background thread (no @spaces.GPU needed —
+  the subprocess already has GPU access process-wide).
+- The streamer is never passed across process boundaries, avoiding pickling errors.
+- model_loader loads the model on CPU then moves to CUDA to avoid caching_allocator_warmup
+  triggering torch._C._cuda_init() before ZeroGPU can intercept it.
+"""
+
+import threading
+from collections.abc import Generator
+from typing import Any
+
+import spaces
+import torch
+from PIL import Image
+from transformers import TextIteratorStreamer
+
+from model_loader import load_model, load_processor
+
+
+@spaces.GPU(duration=120)
+def answer_question_stream(
+    image: Image.Image,
+    question: str,
+    conversation_history: list[dict[str, Any]],
+    current_image_path: str | None,  # noqa: ARG001
+) -> Generator[str, None, None]:
+    """Stream an answer token-by-token about an image using Granite Vision.
+
+    Runs inside @spaces.GPU so CUDA is available throughout. model.generate()
+    runs in a background thread (GPU is process-wide in the ZeroGPU subprocess).
+
+    Args:
+        image: PIL Image to query.
+        question: Question string to ask.
+        conversation_history: Prior conversation turns (role/content dicts).
+        current_image_path: Unused — kept for API compatibility.
+
+    Yields:
+        Accumulated answer text after each token.
+    """
+    processor, model = load_model()
+
+    if processor is None or model is None:
+        yield f"[STUB] Question: {question}\n\nThis is a placeholder response. Model not loaded."
+        return
+
+    try:
+        image = image.convert("RGB")
+
+        if not conversation_history:
+            new_user_turn = {"role": "user", "content": [
+                {"type": "image"},
+                {"type": "text", "text": question},
+            ]}
+        else:
+            new_user_turn = {"role": "user", "content": [
+                {"type": "text", "text": question},
+            ]}
+
+        conversation = [*conversation_history, new_user_turn]
+        text = processor.apply_chat_template(conversation, tokenize=False, add_generation_prompt=True)
+        inputs = processor(text=text, images=image, return_tensors="pt").to(model.device)
+
+        streamer = TextIteratorStreamer(processor.tokenizer, skip_prompt=True, skip_special_tokens=True)
+
+        def _generate() -> None:
+            with torch.inference_mode():
+                model.generate(**inputs, max_new_tokens=4096, use_cache=True, streamer=streamer)
+
+        thread = threading.Thread(target=_generate)
+        thread.start()
+
+        accumulated = ""
+        for token in streamer:
+            if token:
+                accumulated += token
+                yield accumulated
+
+        thread.join()
+
+    except Exception as e:  # noqa: BLE001
+        import traceback
+        traceback.print_exc()
+        yield f"Error: {e!s}"
+
+
+@spaces.GPU(duration=120)
+def answer_question(
+    image: Image.Image,
+    question: str,
+    conversation_history: list[dict[str, Any]],
+    current_image_path: str | None,  # noqa: ARG001
+) -> tuple[str, list[dict[str, Any]], str | None]:
+    """Answer a question about an image using Granite Vision (non-streaming).
+
+    Args:
+        image: PIL Image to query.
+        question: Question string to ask.
+        conversation_history: Prior conversation turns (role/content dicts).
+        current_image_path: Unused — kept for API compatibility.
+
+    Returns:
+        Tuple of (answer_text, updated_history, None).
+    """
+    processor, model = load_model()
+
+    if processor is None or model is None:
+        stub = f"[STUB] Question: {question}\n\nThis is a placeholder response. Model not loaded."
+        return stub, conversation_history, None
+
+    try:
+        image = image.convert("RGB")
+
+        if not conversation_history:
+            new_user_turn = {"role": "user", "content": [
+                {"type": "image"},
+                {"type": "text", "text": question},
+            ]}
+        else:
+            new_user_turn = {"role": "user", "content": [
+                {"type": "text", "text": question},
+            ]}
+
+        conversation = [*conversation_history, new_user_turn]
+        text = processor.apply_chat_template(conversation, tokenize=False, add_generation_prompt=True)
+        inputs = processor(text=text, images=image, return_tensors="pt").to(model.device)
+
+        max_new_tokens = 4096
+        with torch.inference_mode():
+            outputs = model.generate(**inputs, max_new_tokens=max_new_tokens, use_cache=True)
+
+        gen = outputs[0, inputs["input_ids"].shape[1]:]
+        answer = processor.decode(gen, skip_special_tokens=True)
+        if len(gen) >= max_new_tokens:
+            answer += "\n\n[Max token limit reached — response may be truncated]"
+
+        updated_history = [
+            *conversation_history,
+            new_user_turn,
+            {"role": "assistant", "content": [{"type": "text", "text": answer}]},
+        ]
+
+        return answer, updated_history, None
+
+    except Exception as e:  # noqa: BLE001
+        import traceback
+        traceback.print_exc()
+        return f"Error: {e!s}", conversation_history, None

src/model_loader.py

@@ -0,0 +1,87 @@
+"""Shared Granite Vision model loader.
+
+Split into two stages for ZeroGPU compatibility:
+- load_processor(): CPU-only, safe to call at startup or outside @spaces.GPU
+- load_model(): requires CUDA, must only be called inside a @spaces.GPU context
+
+The processor and model are cached globally so they are loaded at most once.
+"""
+
+import os
+from typing import Any
+
+_processor: Any = None
+_model: Any = None
+
+MODEL_ID = "ibm-granite/granite-vision-4.1-4b"
+
+
+def load_processor() -> Any:
+    """Load (or return cached) processor. CPU-only — safe outside @spaces.GPU.
+
+    Returns:
+        AutoProcessor instance, or None if loading fails.
+    """
+    global _processor  # noqa: PLW0603
+
+    if _processor is not None:
+        return _processor
+
+    try:
+        from transformers import AutoProcessor
+
+        token = os.environ.get("HF_TOKEN")
+        _processor = AutoProcessor.from_pretrained(
+            MODEL_ID, trust_remote_code=True, token=token, use_fast=True
+        )
+        print(f"Processor loaded for {MODEL_ID}")
+        return _processor
+
+    except Exception as e:  # noqa: BLE001
+        import traceback
+        print(f"Processor load error: {e}")
+        traceback.print_exc()
+        return None
+
+
+def load_model() -> tuple[Any, Any]:
+    """Load (or return cached) model to CUDA. Must be called inside @spaces.GPU.
+
+    Returns:
+        Tuple of (processor, model), or (None, None) if loading fails.
+    """
+    global _model  # noqa: PLW0603
+
+    processor = load_processor()
+    if processor is None:
+        return None, None
+
+    if _model is not None:
+        return processor, _model
+
+    try:
+        import torch
+        from transformers import AutoModelForImageTextToText
+
+        token = os.environ.get("HF_TOKEN")
+        # Load on CPU first to avoid caching_allocator_warmup triggering
+        # torch._C._cuda_init() before ZeroGPU can intercept it.
+        _model = AutoModelForImageTextToText.from_pretrained(
+            MODEL_ID,
+            trust_remote_code=True,
+            dtype=torch.bfloat16,
+            token=token,
+        ).eval()
+        _model = _model.to("cuda")
+
+        if hasattr(_model, "merge_lora_adapters"):
+            _model = _model.merge_lora_adapters()
+
+        print(f"Model loaded: {MODEL_ID} on cuda")
+        return processor, _model
+
+    except Exception as e:  # noqa: BLE001
+        import traceback
+        print(f"Model load error: {e}")
+        traceback.print_exc()
+        return processor, None

src/pdf_io.py

@@ -0,0 +1,57 @@
+"""PDF I/O utilities for loading and rendering PDFs."""
+
+from PIL import Image
+
+
+def load_pdf_pages(pdf_bytes: bytes, dpi: int = 150, max_pages: int = 10) -> list[Image.Image]:
+    """Load PDF and render each page to a PIL Image.
+
+    Args:
+        pdf_bytes: PDF file as bytes.
+        dpi: Resolution for rendering.
+        max_pages: Maximum number of pages to render.
+
+    Returns:
+        List of PIL Images, one per page.
+    """
+    try:
+        import fitz  # PyMuPDF
+
+        doc = fitz.open(stream=pdf_bytes, filetype="pdf")
+        pages = []
+
+        try:
+            for i in range(min(len(doc), max_pages)):
+                page = doc[i]
+                pix = page.get_pixmap(matrix=fitz.Matrix(dpi / 72, dpi / 72))
+                img = Image.frombytes("RGB", (pix.width, pix.height), pix.samples)
+                pages.append(img)
+        finally:
+            doc.close()
+
+        return pages
+
+    except ImportError:
+        print("PyMuPDF not available, returning placeholder")
+        img = Image.new("RGB", (800, 1000), color=(200, 200, 200))
+        return [img] * 3
+
+
+def get_page_count(pdf_bytes: bytes) -> int:
+    """Get total page count of a PDF.
+
+    Args:
+        pdf_bytes: PDF file as bytes.
+
+    Returns:
+        Total number of pages, or 0 on error.
+    """
+    try:
+        import fitz
+
+        doc = fitz.open(stream=pdf_bytes, filetype="pdf")
+        count = len(doc)
+        doc.close()
+        return count
+    except Exception:  # noqa: BLE001
+        return 0

src/themes/carbon.py

@@ -0,0 +1,147 @@
+"""IBM Carbon theme for gradio demos.
+
+This version builds on top of the Carbon theme to make it more playful with rounded corners, a larger font family to
+enhance readability, and the IBM Cool Gray color palette for better consistency with other IBM Research demos, such as
+Bee.
+"""
+
+import gradio as gr
+from gradio.themes.utils import sizes
+
+theme = gr.themes.Base(
+    primary_hue=gr.themes.Color(
+        c100="#EDF5FF",
+        c200="#D0E2FF",
+        c300="#A6C8FF",
+        c400="#78A9FF",
+        c50="#F9F9FB",
+        c500="#4589FF",
+        c600="#0F62FE",
+        c700="#0043CE",
+        c800="#002D9C",
+        c900="#001D6C",
+        c950="#001141",
+    ),
+    secondary_hue=gr.themes.Color(
+        c100="#EDF5FF",
+        c200="#D0E2FF",
+        c300="#A6C8FF",
+        c400="#78A9FF",
+        c50="#F9F9FB",
+        c500="#4589FF",
+        c600="#0F62FE",
+        c700="#0043CE",
+        c800="#002D9C",
+        c900="#001D6C",
+        c950="#001141",
+    ),
+    neutral_hue=gr.themes.Color(
+        c100="#F2F4F8",
+        c200="#DDE1E6",
+        c300="#C1C7CD",
+        c400="#A2A9B0",
+        c50="#F9F9FB",
+        c500="#878D96",
+        c600="#697077",
+        c700="#4D5358",
+        c800="#393939",
+        c900="#21272A",
+        c950="#121619",
+    ),
+    spacing_size=sizes.spacing_md,  # change spacing to default size
+    radius_size=sizes.radius_md,  # change spacing to default size and Keep Radius to make demo feel more playful
+    text_size=sizes.text_lg,  # change fontsize to default size
+    #   spacing_size: sizes.Size | str = sizes.spacing_md,  #change spacing to default size
+    #         radius_size: sizes.Size | str = sizes.radius_md, #change spacing to default size and Keep Radius to make
+    #                                                           demo feel more playful
+    #         text_size: sizes.Size | str = sizes.text_lg, #change fontsize to default size
+    font=["IBM Plex Sans", "ui-sans-serif", "system-ui", "sans-serif"],  # update font
+    font_mono=["IBM Plex Mono", "ui-monospace", "Consolas", "monospace"],  # update font
+).set(
+    # Colors
+    background_fill_primary="*neutral_100",  # Coolgray10 background
+    background_fill_primary_dark="*neutral_950",  # Coolgray95 background for dark mode
+    slider_color="*primary_600",  # Blue60
+    slider_color_dark="*primary_500",  # Blue50
+    # Shadows
+    shadow_drop="0 1px 4px 0 rgb(0 0 0 / 0.1)",
+    shadow_drop_lg="0 2px 5px 0 rgb(0 0 0 / 0.1)",
+    # Block Labels
+    block_background_fill="white",
+    block_label_background_fill="white",  # same color as blockback gound fill
+    block_label_radius="*radius_md",
+    block_label_text_size="*text_md",
+    block_label_text_weight="600",
+    block_label_text_color="black",
+    block_label_text_color_dark="white",
+    block_title_radius="*block_label_radius",
+    block_title_background_fill="*block_label_background_fill",
+    block_title_text_weight="600",
+    block_title_text_color="black",
+    block_title_text_color_dark="white",
+    block_label_margin="*spacing_md",
+    # Inputs
+    input_background_fill="white",
+    input_background_fill_dark="*block-background-fill",
+    input_border_color="*neutral_100",
+    input_shadow="*shadow_drop",
+    input_shadow_focus="*shadow_drop_lg",
+    checkbox_shadow="none",
+    # Buttons
+    shadow_spread="6px",
+    button_primary_shadow="*shadow_drop_lg",
+    button_primary_shadow_hover="*shadow_drop_lg",
+    button_primary_shadow_active="*shadow_inset",
+    button_secondary_shadow="*shadow_drop_lg",
+    button_secondary_shadow_hover="*shadow_drop_lg",
+    button_secondary_shadow_active="*shadow_inset",
+    checkbox_label_shadow="*shadow_drop_lg",
+    button_primary_background_fill="*primary_600",
+    button_primary_background_fill_hover="*primary_500",
+    button_primary_background_fill_hover_dark="*primary_500",
+    button_primary_text_color="white",
+    button_secondary_background_fill="white",
+    button_secondary_background_fill_hover="*neutral_100",
+    button_secondary_background_fill_dark="*neutral_800",  # Secondary cool gray 80
+    button_secondary_background_fill_hover_dark="*primary_500",
+    button_secondary_text_color="*neutral_800",
+    button_cancel_background_fill="*button_secondary_background_fill",
+    button_cancel_background_fill_hover="*button_secondary_background_fill_hover",
+    button_cancel_background_fill_hover_dark="*button_secondary_background_fill_hover",
+    button_cancel_text_color="*button_secondary_text_color",
+    checkbox_label_background_fill_selected="*primary_200",
+    checkbox_label_background_fill_selected_dark="*primary_500",
+    checkbox_border_width="1px",
+    checkbox_border_color="*neutral_200",
+    checkbox_background_color_dark="*neutral_700",  # Jan 18 test to fix checkbox, radio button background color
+    checkbox_background_color_selected="*primary_600",
+    checkbox_background_color_selected_dark="*primary_500",
+    checkbox_border_color_focus="*primary_600",
+    checkbox_border_color_focus_dark="*primary_500",
+    checkbox_border_color_selected="*primary_600",
+    checkbox_border_color_selected_dark="*primary_500",
+    checkbox_label_text_color_selected="black",
+    # Borders
+    block_border_width="1px",  # test example border
+    panel_border_width="1px",
+    # Chatbubble related colors
+    # light
+    # color_accent = "*secondary_400",
+    border_color_accent_subdued="*color_accent_soft",  # chatbubble human border color, use Blue 20 as an accent color
+    color_accent_soft="*secondary_200",  # chatbubble human color
+    # darkmode
+    # chatbubble human border color in darkmode, use Blue 20 as an accent color
+    border_color_accent_subdued_dark="*secondary_500",
+    color_accent_soft_dark="*secondary_500",  # chatbubble human color in dark mode
+    # Chatbot related font
+    chatbot_text_size="*text_md",  # make it larger
+    # additional dark mode related tweaks:
+    # block_background_fill_dark="*neutral_950", # Jan 18 test coolgray95 background for dark mode
+    block_label_background_fill_dark="*neutral_800",  # same color as blockback gound fill
+    block_title_background_fill_dark="*block_label_background_fill",
+    # input_background_fill_dark="*neutral_800", #This attribute help match fill color cool gray 80 to match background
+    #                                             however cause the problem for the general theme.
+    #  input_shadow_dark="*shadow_drop", #Test if it could make the border without the color
+    # input_border_color_dark="*neutral_200",#add attribute for border Jan 18
+    checkbox_border_color_dark="*neutral_600",  # Jan 18 test to fix border
+)

src/themes/research_monochrome.py

@@ -0,0 +1,152 @@
+"""IBM Research Monochrome theme for gradio demos.
+
+This version is a variation of CarbonSoft style, where the primary button is dark gray to create monochrome style. This
+version uses the style from Research demos such as Bee to make it more playful with rounded corners, a larger font
+family to enhance readability, and the IBM Cool Gray color palette for better consistency with other IBM Research demos,
+such as Bee.
+"""
+
+import gradio as gr
+from gradio.themes.utils import sizes
+
+theme = gr.themes.Base(
+    primary_hue=gr.themes.Color(
+        c100="#EDF5FF",
+        c200="#D0E2FF",
+        c300="#A6C8FF",
+        c400="#78A9FF",
+        c50="#F9F9FB",
+        c500="#4589FF",
+        c600="#0F62FE",
+        c700="#0043CE",
+        c800="#002D9C",
+        c900="#001D6C",
+        c950="#001141",
+    ),
+    secondary_hue=gr.themes.Color(
+        c100="#EDF5FF",
+        c200="#D0E2FF",
+        c300="#A6C8FF",
+        c400="#78A9FF",
+        c50="#F9F9FB",
+        c500="#4589FF",
+        c600="#0F62FE",
+        c700="#0043CE",
+        c800="#002D9C",
+        c900="#001D6C",
+        c950="#001141",
+    ),
+    neutral_hue=gr.themes.Color(
+        c100="#F2F4F8",
+        c200="#DDE1E6",
+        c300="#C1C7CD",
+        c400="#A2A9B0",
+        c50="#F9F9FB",
+        c500="#878D96",
+        c600="#697077",
+        c700="#4D5358",
+        c800="#393939",
+        c900="#21272A",
+        c950="#121619",
+    ),
+    spacing_size=sizes.spacing_md,  # change spacing to default size
+    radius_size=sizes.radius_md,  # change spacing to default size and Keep Radius to make demo feel more playful
+    text_size=sizes.text_md,  # change fontsize to default size
+    #   spacing_size: sizes.Size | str = sizes.spacing_md,  #change spacing to default size
+    #         radius_size: sizes.Size | str = sizes.radius_md, #change spacing to default size and Keep Radius to make
+    #                                                           demo feel more playful
+    #         text_size: sizes.Size | str = sizes.text_lg, #change fontsize to default size
+    font=["IBM Plex Sans", "ui-sans-serif", "system-ui", "sans-serif"],  # update font
+    font_mono=["IBM Plex Mono", "ui-monospace", "Consolas", "monospace"],  # update font
+).set(
+    # Colors
+    background_fill_primary="*neutral_100",  # Coolgray10 background
+    background_fill_primary_dark="*neutral_950",  # Coolgray95 background for dark mode
+    # Change blue to black to create monochrome style
+    slider_color="*neutral_900",
+    slider_color_dark="*primary_500",
+    # Shadows
+    shadow_drop="0 1px 4px 0 rgb(0 0 0 / 0.1)",
+    shadow_drop_lg="0 2px 5px 0 rgb(0 0 0 / 0.1)",
+    # Block Labels
+    block_background_fill="white",
+    block_label_background_fill="white",  # same color as blockback gound fill
+    block_label_radius="*radius_md",
+    block_label_text_size="*text_md",
+    block_label_text_weight="600",
+    block_label_text_color="black",
+    block_label_text_color_dark="white",
+    block_title_radius="*block_label_radius",
+    block_title_background_fill="*block_label_background_fill",
+    block_title_text_weight="400",
+    block_title_text_color="black",
+    block_title_text_color_dark="white",
+    block_label_margin="*spacing_md",
+    # Inputs
+    input_background_fill="white",
+    input_background_fill_dark="*block-background-fill",
+    input_border_color="*neutral_100",
+    input_shadow="*shadow_drop",
+    input_shadow_dark="0 1px 4px #000",
+    input_shadow_focus="*shadow_drop_lg",
+    checkbox_shadow="none",
+    # Buttons
+    shadow_spread="6px",
+    button_primary_shadow="*shadow_drop_lg",
+    button_primary_shadow_hover="*shadow_drop_lg",
+    button_primary_shadow_active="*shadow_inset",
+    button_secondary_shadow="*shadow_drop_lg",
+    button_secondary_shadow_hover="*shadow_drop_lg",
+    button_secondary_shadow_active="*shadow_inset",
+    checkbox_label_shadow="*shadow_drop_lg",
+    # Change blue to black to create monochrome style
+    button_primary_background_fill="*neutral_900",
+    button_primary_background_fill_dark="*neutral_600",
+    button_primary_background_fill_hover="*neutral_700",
+    button_primary_background_fill_hover_dark="*primary_500",  # hover to be blue
+    button_primary_text_color="white",
+    button_secondary_background_fill="white",
+    button_secondary_background_fill_hover="*neutral_100",
+    button_secondary_background_fill_dark="*neutral_800",  # Secondary cool gray 80
+    button_secondary_background_fill_hover_dark="*primary_500",
+    button_secondary_text_color="*neutral_800",
+    button_cancel_background_fill="*button_secondary_background_fill",
+    button_cancel_background_fill_hover="*button_secondary_background_fill_hover",
+    button_cancel_background_fill_hover_dark="*button_secondary_background_fill_hover",
+    button_cancel_text_color="*button_secondary_text_color",
+    checkbox_label_background_fill_selected="*primary_200",
+    checkbox_label_background_fill_selected_dark="*primary_500",
+    checkbox_border_width="1px",
+    checkbox_border_color="*neutral_200",
+    checkbox_background_color_dark="*neutral_700",  # Jan 18 test to fix checkbox, radio button background color
+    checkbox_background_color_selected="*primary_600",
+    checkbox_background_color_selected_dark="*primary_500",
+    checkbox_border_color_focus="*primary_600",
+    checkbox_border_color_focus_dark="*primary_500",
+    checkbox_border_color_selected="*primary_600",
+    checkbox_border_color_selected_dark="*primary_500",
+    checkbox_label_text_color_selected="black",
+    # Borders
+    block_border_width="1px",  # test example border
+    panel_border_width="1px",
+    # Chatbubble related colors
+    # light
+    # color_accent = "*secondary_400",
+    border_color_accent_subdued="*color_accent_soft",  # chatbubble human border color, use Blue 20 as an accent color
+    color_accent_soft="*secondary_200",  # chatbubble human color
+    # darkmode
+    # chatbubble human border color in darkmode, use Blue 20 as an accent color
+    border_color_accent_subdued_dark="*secondary_500",
+    color_accent_soft_dark="*secondary_500",  # chatbubble human color in dark mode
+    # Chatbot related font
+    chatbot_text_size="*text_md",  # make it larger
+    # additional dark mode related tweaks:
+    # block_background_fill_dark="*neutral_950", # Jan 18 test coolgray95 background for dark mode
+    block_label_background_fill_dark="*neutral_800",  # same color as blockback gound fill
+    block_title_background_fill_dark="*block_label_background_fill",
+    # input_background_fill_dark="*neutral_800", #This attribute help match fill color cool gray 80 to match background
+    #                                             however cause the problem for the general theme.
+    #  input_shadow_dark="*shadow_drop", #Test if it could make the border without the color
+    # input_border_color_dark="*neutral_200",#add attribute for border Jan 18
+    checkbox_border_color_dark="*neutral_600",  # Jan 18 test to fix border
+)

src/ui_state.py

@@ -0,0 +1,43 @@
+"""UI state management for the document intelligence demo.
+
+Per-session state via factory function + shared caches.
+"""
+
+import hashlib
+
+
+def create_initial_state() -> dict:
+    """Create a fresh per-session state dictionary.
+
+    Returns:
+        Initial state with all fields set to defaults.
+    """
+    return {
+        "uploaded_file_hash": None,
+        "uploaded_file_bytes": None,
+        "parsed_result": {},
+        "page_images": [],
+        "figures_info": [],
+        "selected_figure": None,
+        "last_csv": None,
+        "current_figure_index": 0,
+        "conversation_history": [],
+        "current_image_path": None,
+    }
+
+
+# Module-level shared caches (keyed by content hash, safe to share across sessions)
+parse_cache: dict[str, dict] = {}
+page_cache: dict[str, list] = {}
+
+
+def hash_bytes(data: bytes) -> str:
+    """Generate SHA256 hash of bytes.
+
+    Args:
+        data: Bytes to hash.
+
+    Returns:
+        Hex string of SHA256 hash.
+    """
+    return hashlib.sha256(data).hexdigest()