initial commit

.gitattributes copy

@@ -0,0 +1,2 @@
+*.csv filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,174 @@
+# 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/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

Dockerfile

@@ -0,0 +1,16 @@
+FROM python:3.9-slim
+
+WORKDIR /app
+
+# Copy requirements and install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the application code
+COPY . .
+
+# Expose the Streamlit port
+EXPOSE 8501
+
+# Command to run the application
+CMD ["streamlit", "run", "app.py", "--server.address=0.0.0.0", "--server.port=8501"]

LICENSE

@@ -0,0 +1,674 @@
+ GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

README.md

@@ -1,11 +1,110 @@
+# [Project: Delivery Route Optimization](https://huggingface.co/spaces/Jing997/DeliveryRouteOptimisation)
+
+![Delivery Route Optimization Demo](gif/delivery_route_optimisation.gif)
+
+This project is a **Delivery Route Optimization** tool built using Streamlit. It aims to optimize delivery routes for a fleet of vehicles while considering constraints such as delivery time windows, vehicle capacity, and traffic conditions.
+
+
+### Key Features
+1. **Route Optimization**:
+   - Solve the **Vehicle Routing Problem (VRP)** to determine the most efficient routes for a fleet of vehicles.
+   - Incorporate constraints like:
+     - Delivery time windows.
+     - Vehicle capacity.
+     - Traffic conditions.
+
+2. **Map Visualization**:
+   - Display optimized routes on an interactive map using **Folium**.
+   - Highlight delivery stops, start and end points, and route distances.
+
+3. **Calendar View**:
+   - Provide a calendar-based schedule for deliveries.
+   - Allow users to view and manage delivery schedules for specific days or weeks.
+
+4. **Real-Time Updates**:
+   - Enable real-time updates for route changes due to unexpected events (e.g., traffic congestion, vehicle breakdowns).
+   - Re-optimize routes dynamically and update the map and calendar views.
+
+### Tools and Technologies
+- **Python**: Core programming language for optimization and application logic.
+- **Google OR-Tools**: Solve the Vehicle Routing Problem (VRP) with constraints.
+- **Streamlit**: Build an interactive web application for route visualization and schedule management.
+- **Folium**: Create interactive maps for route visualization.
+- **Synthetic Data**: Integrate real-time traffic data for dynamic route adjustments.
+
 ---
-title: DeliveryRouteOptimisation
-emoji: 🌍
-colorFrom: yellow
-colorTo: red
-sdk: docker
-pinned: false
-license: gpl-2.0
+
+## Project Structure
+
+```
+streamlit-app-template
+├── src
+│   ├── app.py                # Main entry point of the Streamlit application
+│   ├── components            # Directory for reusable UI components
+│   │   └── __init__.py
+│   ├── pages                 # Directory for different pages of the application
+│   │   └── __init__.py
+│   ├── utils                 # Directory for utility functions
+│   │   └── __init__.py
+├── requirements.txt          # List of dependencies for the application
+├── .streamlit                # Configuration settings for Streamlit
+│   ├── config.toml
+├── img                       # Folder for storing images
+│   └── delivery_route_network.png
+├── .gitignore                # Files and directories to ignore in Git
+├── README.md                 # Documentation for the project
+└── LICENSE                   # Licensing information
+```
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Installation
+
+To get started with this Streamlit application template, follow these steps:
+
+1. Clone the repository:
+   ```
+   git clone https://github.com/yourusername/streamlit-app-template.git
+   cd streamlit-app-template
+   ```
+
+2. Create a virtual environment (optional but recommended):
+   ```
+   python -m venv venv
+   source venv/bin/activate  # On macOS/Linux
+   venv\Scripts\activate     # On Windows
+   ```
+
+3. Install the required dependencies:
+   ```
+   pip install -r requirements.txt
+   ```
+
+4. Run the Streamlit application:
+   ```
+   streamlit run src/app.py
+   ```
+
+---
+
+## Deployment
+
+This application is deployed on Hugging Face Spaces and is accessible at:
+
+🚀 [Delivery Route Optimization App](https://huggingface.co/spaces/Jing997/DeliveryRouteOptimisation)
+
+The deployed version provides all the features of the local application without requiring any installation. You can:
+
+- View and analyze optimized delivery routes
+- Interact with the map visualization
+- Explore the calendar view of scheduled deliveries
+- Test different optimization parameters
+- Filter deliveries by date, status, and priority
+
+The app is automatically updated whenever changes are pushed to the connected GitHub repository.
+
+---
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

app.py

@@ -0,0 +1,35 @@
+# Main entry point of the Streamlit application
+
+import streamlit as st
+import sys
+from pathlib import Path
+
+# Import all pages from the pages module 
+from src.pages import home_page, about_page, contact_page, map_page, optimize_page
+
+def main():
+    st.set_page_config(
+        page_title="Delivery Route Optimization",
+        page_icon="🚚",
+        layout="wide",
+        initial_sidebar_state="expanded",
+    )
+    
+    st.sidebar.title("Navigation")
+    
+    # Sidebar navigation
+    pages = {
+        "Home": home_page,
+        "Map": map_page,
+        "Optimizer": optimize_page,  # Add the new page
+        "About": about_page,
+        "Contact": contact_page
+    }
+    
+    selection = st.sidebar.radio("Go to", list(pages.keys()))
+    
+    # Render the selected page
+    pages[selection]()
+
+if __name__ == "__main__":
+    main()

config.toml

@@ -0,0 +1,17 @@
+[general]
+email = "jinghui.me@gmail.com"
+# The email address for the Streamlit sharing service.
+
+[server]
+headless = true
+port = 8501
+enableCORS = false
+# Configuration for the server, including running in headless mode and setting the port.
+
+[theme]
+primaryColor = "#F39C12"
+backgroundColor = "#FFFFFF"
+secondaryBackgroundColor = "#F0F0F0"
+textColor = "#000000"
+font = "sans serif"
+# Theme settings for the Streamlit application, including colors and font.

huggingface-metadata.yaml

@@ -0,0 +1,8 @@
+# File: .github/huggingface-metadata.yaml
+title: Streamlit Scheduler App
+emoji: 🚚
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+app_port: 8501
+pinned: false

requirements.txt

@@ -0,0 +1,11 @@
+streamlit>=1.24.0
+pandas>=1.5.0
+numpy>=1.23.0
+plotly>=5.13.0
+folium>=0.14.0
+streamlit-folium>=0.11.0
+requests>=2.28.0
+python-dotenv>=1.0.0
+ortools>=9.6.0
+geopy
+matplotlib

src/components/__init__.py

@@ -0,0 +1 @@
+# This file is intentionally left blank.

src/components/map_visualization.py

@@ -0,0 +1,204 @@
+import os
+import sys
+from pathlib import Path
+import pandas as pd
+import folium
+import streamlit as st
+
+def load_data():
+    """
+    Load delivery and vehicle data from CSV files
+    
+    Returns:
+        tuple: (delivery_data, vehicle_data)
+    """
+    # Get the project root directory
+    root_dir = Path(__file__).resolve().parent.parent.parent
+    
+    # Define data paths
+    delivery_data_path = os.path.join(root_dir, 'data', 'delivery-data', 'delivery_data.csv')
+    vehicle_data_path = os.path.join(root_dir, 'data', 'vehicle-data', 'vehicle_data.csv')
+    
+    # Load data
+    try:
+        delivery_data = pd.read_csv(delivery_data_path)
+        vehicle_data = pd.read_csv(vehicle_data_path)
+        return delivery_data, vehicle_data
+    except FileNotFoundError as e:
+        st.error(f"Could not load data: {e}")
+        st.info("Please generate the data first by running: python src/utils/generate_all_data.py")
+        return None, None
+
+def create_delivery_map(delivery_data=None, vehicle_data=None, show_deliveries=True, show_depots=True, 
+                       date_filter=None, status_filter=None, priority_filter=None):
+    """
+    Create a Folium map with markers for deliveries and vehicle depots
+    
+    Parameters:
+        delivery_data (pd.DataFrame): Delivery data
+        vehicle_data (pd.DataFrame): Vehicle data
+        show_deliveries (bool): Whether to show delivery markers
+        show_depots (bool): Whether to show depot markers
+        date_filter (str): Filter deliveries by date
+        status_filter (str): Filter deliveries by status
+        priority_filter (str): Filter deliveries by priority
+    
+    Returns:
+        folium.Map: Folium map with markers
+    """
+    # If data not provided, load it
+    if delivery_data is None or vehicle_data is None:
+        delivery_data, vehicle_data = load_data()
+        if delivery_data is None or vehicle_data is None:
+            return None
+    
+    # Apply filters to delivery data
+    if date_filter is not None:
+        delivery_data = delivery_data[delivery_data['delivery_date'] == date_filter]
+        
+    if status_filter is not None:
+        delivery_data = delivery_data[delivery_data['status'] == status_filter]
+        
+    if priority_filter is not None:
+        delivery_data = delivery_data[delivery_data['priority'] == priority_filter]
+    
+    # Create map centered around Singapore
+    singapore_coords = [1.3521, 103.8198]  # Center of Singapore
+    m = folium.Map(location=singapore_coords, zoom_start=12)
+    
+    # Add delivery markers
+    if show_deliveries and not delivery_data.empty:
+        for _, row in delivery_data.iterrows():
+            # Create popup content with delivery information
+            popup_content = f"""
+                <b>Delivery ID:</b> {row['delivery_id']}<br>
+                <b>Customer:</b> {row['customer_name']}<br>
+                <b>Address:</b> {row['address']}<br>
+                <b>Time Window:</b> {row['time_window']}<br>
+                <b>Status:</b> {row['status']}<br>
+                <b>Priority:</b> {row['priority']}<br>
+                <b>Weight:</b> {row['weight_kg']} kg<br>
+                <b>Volume:</b> {row['volume_m3']} m³
+            """
+            
+            # Set marker color based on priority
+            color_map = {'High': 'red', 'Medium': 'orange', 'Low': 'blue'}
+            color = color_map.get(row['priority'], 'blue')
+            
+            # Add marker to map
+            folium.Marker(
+                location=[row['latitude'], row['longitude']],
+                popup=folium.Popup(popup_content, max_width=300),
+                tooltip=f"Delivery {row['delivery_id']}: {row['customer_name']}",
+                icon=folium.Icon(color=color, icon="package", prefix="fa")
+            ).add_to(m)
+    
+    # Add depot markers
+    if show_depots and not vehicle_data.empty:
+        for _, row in vehicle_data.iterrows():
+            # Create popup content with vehicle information
+            popup_content = f"""
+                <b>Vehicle ID:</b> {row['vehicle_id']}<br>
+                <b>Type:</b> {row['vehicle_type']}<br>
+                <b>Driver:</b> {row['driver_name']}<br>
+                <b>Status:</b> {row['status']}<br>
+                <b>Capacity:</b> {row['max_weight_kg']} kg / {row['max_volume_m3']} m³<br>
+                <b>Working Hours:</b> {row['start_time']} - {row['end_time']}
+            """
+            
+            # Add marker to map
+            folium.Marker(
+                location=[row['depot_latitude'], row['depot_longitude']],
+                popup=folium.Popup(popup_content, max_width=300),
+                tooltip=f"Depot: {row['vehicle_id']}",
+                icon=folium.Icon(color="green", icon="truck", prefix="fa")
+            ).add_to(m)
+    
+    return m
+
+def display_map_component():
+    """
+    Display the map visualization component in Streamlit
+    """
+    st.subheader("Delivery and Depot Locations")
+    
+    # Load data
+    delivery_data, vehicle_data = load_data()
+    if delivery_data is None or vehicle_data is None:
+        return
+    
+    # Create sidebar filters
+    with st.sidebar:
+        st.subheader("Map Filters")
+        
+        # Show/hide options
+        show_deliveries = st.checkbox("Show Deliveries", value=True)
+        show_depots = st.checkbox("Show Depots", value=True)
+        
+        # Delivery date filter
+        dates = sorted(delivery_data['delivery_date'].unique())
+        selected_date = st.selectbox(
+            "Filter by Date",
+            options=["All"] + list(dates),
+            index=0
+        )
+        date_filter = None if selected_date == "All" else selected_date
+        
+        # Delivery status filter
+        statuses = sorted(delivery_data['status'].unique())
+        selected_status = st.selectbox(
+            "Filter by Status",
+            options=["All"] + list(statuses),
+            index=0
+        )
+        status_filter = None if selected_status == "All" else selected_status
+        
+        # Delivery priority filter
+        priorities = sorted(delivery_data['priority'].unique())
+        selected_priority = st.selectbox(
+            "Filter by Priority",
+            options=["All"] + list(priorities),
+            index=0
+        )
+        priority_filter = None if selected_priority == "All" else selected_priority
+    
+    # Display statistics
+    col1, col2, col3 = st.columns(3)
+    
+    # Apply filters for stats calculation
+    filtered_delivery_data = delivery_data
+    if date_filter:
+        filtered_delivery_data = filtered_delivery_data[filtered_delivery_data['delivery_date'] == date_filter]
+    if status_filter:
+        filtered_delivery_data = filtered_delivery_data[filtered_delivery_data['status'] == status_filter]
+    if priority_filter:
+        filtered_delivery_data = filtered_delivery_data[filtered_delivery_data['priority'] == priority_filter]
+    
+    with col1:
+        st.metric("Total Deliveries", filtered_delivery_data.shape[0])
+    
+    with col2:
+        st.metric("Total Weight", f"{filtered_delivery_data['weight_kg'].sum():.2f} kg")
+    
+    with col3:
+        st.metric("Available Vehicles", vehicle_data[vehicle_data['status'] == 'Available'].shape[0])
+    
+    # Create and display the map
+    delivery_map = create_delivery_map(
+        delivery_data=delivery_data,
+        vehicle_data=vehicle_data,
+        show_deliveries=show_deliveries,
+        show_depots=show_depots,
+        date_filter=date_filter,
+        status_filter=status_filter,
+        priority_filter=priority_filter
+    )
+    
+    if delivery_map:
+        folium_static(delivery_map, width=800, height=600)
+    else:
+        st.error("Could not create map. Please check that data is available.")
+
+if __name__ == "__main__":
+    # Run the map visualization component
+    display_map_component()

src/pages/__init__.py

@@ -0,0 +1,8 @@
+# Import all page functions to make them available from this package
+from src.pages._home_page import home_page
+from src.pages._about_page import about_page
+from src.pages._contact_page import contact_page
+from src.pages._map_page import map_page
+from src.pages._optimize_page import optimize_page
+
+__all__ = ['home_page', 'about_page', 'contact_page', 'map_page', 'optimize_page']

src/pages/_about_page.py

@@ -0,0 +1,97 @@
+import streamlit as st
+
+def about_page():
+    """
+    Render the about page
+    """
+    st.title("About This Project")
+    
+    st.write("""
+    ## Project Overview
+    
+    This project is a **Delivery Route Optimization** tool built using Streamlit. It aims to optimize delivery
+    routes for a fleet of vehicles while considering constraints such as delivery time windows, vehicle capacity,
+    and traffic conditions.
+             
+    """)
+
+    # Project overview from about page   
+    st.write("""
+    This project is a **Delivery Route Optimization** tool that provides an interactive web interface
+    for solving complex logistics challenges. It uses advanced algorithms to determine the most efficient
+    delivery routes while balancing various constraints and business priorities.
+    """)
+    
+    # Key features in columns
+    st.subheader("Key Features")
+    
+    col1, col2 = st.columns(2)
+    
+    with col1:
+        st.markdown("""
+        #### Route Optimization
+        - Solves the **Vehicle Routing Problem (VRP)** to determine efficient routes
+        - Incorporates constraints like time windows and vehicle capacity
+        - Prioritizes deliveries based on importance and urgency
+        
+        #### Map Visualization
+        - Displays optimized routes on an interactive map
+        - Highlights delivery stops and depot locations
+        - Provides detailed route information and statistics
+        """)
+        
+    with col2:
+        st.markdown("""
+        #### Calendar View
+        - Calendar-based schedule for deliveries
+        - Shows delivery timeline and workload distribution
+        - Helps manage delivery schedules efficiently
+        
+        #### Interactive Dashboard
+        - Real-time delivery status monitoring
+        - Data filtering and visualization options
+        - Customizable optimization parameters
+        """)
+    
+    # Tools and technologies in an expander
+    with st.expander("Tools and Technologies"):
+        col1, col2, col3 = st.columns(3)
+        
+        with col1:
+            st.markdown("""
+            #### Core Technologies
+            - **Python** - Main programming language
+            - **Streamlit** - Interactive web interface
+            - **Google OR-Tools** - Optimization engine
+            """)
+            
+        with col2:
+            st.markdown("""
+            #### Data Visualization
+            - **Folium** - Interactive maps
+            - **Plotly** - Charts and timelines
+            - **Pandas** - Data processing
+            """)
+            
+        with col3:
+            st.markdown("""
+            #### Routing Services
+            - **OSRM** - Road distances calculation
+            - **TimeMatrix** - Travel time estimation
+            - **Geocoding** - Location services
+            """)
+    
+    # Navigation guidance
+    st.header("Getting Started")
+    st.write("""
+    Use the sidebar navigation to explore the application:
+    
+    - **Map**: Visualize delivery locations and vehicle depots
+    - **Optimizer**: Create optimized delivery routes
+    - **About**: Learn more about this application
+    - **Contact**: Get in touch with the team
+    """)
+
+# Make sure the function can be executed standalone
+if __name__ == "__main__":
+    about_page()

src/pages/_contact_page.py

@@ -0,0 +1,28 @@
+import streamlit as st
+
+def contact_page():
+    """
+    Render the contact page
+    """
+    st.title("Contact")
+    
+    st.write("""
+    ### Get in Touch
+    
+    For questions, feedback, or suggestions about this application, please feel free to reach out.
+    
+    **Email**: jinghui.me@gmail.com
+    
+    ### Repository
+    
+    This project is open-source. Find the code on GitHub:
+    [streamlit-schedular-app](https://github.com/yourusername/streamlit-schedular-app)
+    
+    ### License
+    
+    This project is licensed under the MIT License. See the LICENSE file for more details.
+    """)
+
+# Make sure the function can be executed standalone
+if __name__ == "__main__":
+    contact_page()

src/pages/_home_page.py

@@ -0,0 +1,74 @@
+import streamlit as st
+import pandas as pd
+import os
+from pathlib import Path
+
+def home_page():
+    """
+    Render the combined home and about page
+    """
+    st.title("Delivery Route Optimization")
+    
+    st.write("""
+    Welcome to the Delivery Route Optimization application! This tool helps logistics teams
+    optimize delivery routes for a fleet of vehicles while considering constraints such as delivery time windows,
+    vehicle capacity, and traffic conditions.
+    
+    Use the navigation sidebar to explore different features of this application.
+    """)
+    
+    # Quick stats from data at the top
+    try:
+        # Get data paths
+        root_dir = Path(__file__).resolve().parent.parent.parent
+        delivery_path = os.path.join(root_dir, 'data', 'delivery-data', 'delivery_data.csv')
+        vehicle_path = os.path.join(root_dir, 'data', 'vehicle-data', 'vehicle_data.csv')
+        
+        if os.path.exists(delivery_path) and os.path.exists(vehicle_path):
+            # Load data for stats
+            delivery_data = pd.read_csv(delivery_path)
+            vehicle_data = pd.read_csv(vehicle_path)
+            
+            # Display stats
+            st.subheader("Current Statistics")
+            col1, col2, col3 = st.columns(3)
+            with col1:
+                st.metric("Total Deliveries", len(delivery_data))
+            with col2:
+                st.metric("Total Vehicles", len(vehicle_data))
+            with col3:
+                pending = delivery_data[delivery_data['status'] == 'Pending'] if 'status' in delivery_data.columns else []
+                st.metric("Pending Deliveries", len(pending))
+                
+            # Add more detailed stats in an expander
+            with st.expander("View More Statistics"):
+                # Status breakdown
+                if 'status' in delivery_data.columns:
+                    st.write("#### Delivery Status Breakdown")
+                    status_counts = delivery_data['status'].value_counts().reset_index()
+                    status_counts.columns = ['Status', 'Count']
+                    status_chart = st.bar_chart(status_counts.set_index('Status'))
+                
+                # Priority breakdown
+                if 'priority' in delivery_data.columns:
+                    st.write("#### Delivery Priority Breakdown")
+                    priority_counts = delivery_data['priority'].value_counts().reset_index()
+                    priority_counts.columns = ['Priority', 'Count']
+                    priority_chart = st.bar_chart(priority_counts.set_index('Priority'))
+        else:
+            st.info("Please generate data first to see statistics")
+            st.code("python src/utils/generate_all_data.py")
+    except Exception as e:
+        st.info("Generate data first to see statistics")
+        st.code("python src/utils/generate_all_data.py")
+    
+    # Add the image
+    img_path = Path(__file__).resolve().parent.parent.parent / "img" / "delivery-route-network.jpg"
+    if os.path.exists(img_path):
+        st.image(str(img_path), caption="Delivery Route Network")
+
+
+# Make sure the function can be executed standalone
+if __name__ == "__main__":
+    st.set_page_config(page_title="Home - Delivery Route Optimization", page_icon="🚚", layout="wide")
+    home_page()

src/pages/_map_page.py

@@ -0,0 +1,524 @@
+import streamlit as st
+import folium
+from streamlit_folium import folium_static
+import pandas as pd
+import os
+import plotly.figure_factory as ff
+import plotly.express as px
+from pathlib import Path
+from datetime import datetime, timedelta
+import numpy as np
+
+def map_page():
+    """
+    Render the map visualization page with delivery and depot locations.
+    Can be called from app.py to display within the main application.
+    """
+    st.title("Delivery Route Map")
+    st.write("""
+    This page visualizes the delivery locations and vehicle depots on an interactive map.
+    Use the filters in the sidebar to customize the view.
+    """)
+
+
+    # Add help section with expander
+    with st.expander("📚 How to Use the Map Pageß"):
+        st.markdown("""
+        ## Step-by-Step Guide to the Map Page
+        
+        The Map page provides an interactive visualization of all delivery locations and vehicle depots. It helps you understand delivery distribution, monitor delivery status, and plan logistics operations.
+        
+        ### 1. Map Navigation
+        
+        - **Pan**: Click and drag to move around the map
+        - **Zoom**: Use the scroll wheel or the +/- buttons in the top-left corner
+        - **View Details**: Click on any marker to see detailed information about that delivery or depot
+        
+        ### 2. Using Map Filters (Sidebar)
+        
+        - **Show/Hide Elements**:
+          - Toggle "Show Deliveries" to display or hide delivery markers
+          - Toggle "Show Depots" to display or hide vehicle depot markers
+          - Enable "Show Data Table" to view raw delivery data below the map
+          - Enable "Show Calendar View" to see delivery schedules organized by date
+        
+        - **Filter by Attributes**:
+          - Use "Filter by Priority" to show only deliveries of selected priority levels (High, Medium, Low)
+          - Use "Filter by Status" to show only deliveries with selected statuses (Pending, In Transit, Delivered)
+        
+        - **Date Filtering**:
+          - Use the "Date Range" selector to focus on deliveries within specific dates
+          - This affects both the map display and the calendar view
+        
+        ### 3. Understanding the Map Markers
+        
+        - **Delivery Markers**:
+          - Red markers: High priority deliveries
+          - Orange markers: Medium priority deliveries
+          - Blue markers: Low priority deliveries
+        
+        - **Depot Markers**:
+          - Green house icons: Vehicle depot locations
+        
+        ### 4. Using the Calendar View
+        
+        - Select specific dates from the dropdown to view scheduled deliveries
+        - Each tab shows deliveries for one selected date
+        - Timeline bars are color-coded by priority (red=High, orange=Medium, blue=Low)
+        - Hover over timeline bars to see detailed delivery information
+        - Check the summary metrics below each calendar for quick insights
+        
+        ### 5. Reading the Delivery Statistics
+        
+        - The top section shows key metrics about displayed deliveries:
+          - Total number of deliveries shown
+          - Total weight of all displayed deliveries
+          - Number of pending deliveries
+          - Breakdown of deliveries by status
+        
+        ### 6. Data Table Features
+        
+        When "Show Data Table" is enabled:
+        - Green highlighted rows: Completed deliveries
+        - Red highlighted rows: Urgent high-priority deliveries due within the next week
+        - Sort any column by clicking the column header
+        - Search across all fields using the search box
+        
+        This map view helps you visualize your delivery operations geographically while the calendar provides a time-based perspective of your delivery schedule.
+        """)
+    
+    # Initialize session state variables for filters
+    if 'map_filters' not in st.session_state:
+        st.session_state.map_filters = {
+            'selected_dates': ["All"],
+            'priority_filter': [],
+            'status_filter': [],
+            'date_range': [None, None],
+            'show_calendar': True,
+            'show_map': True,
+            'show_data_table': False,
+            'cluster_markers': True
+        }
+    
+    # Create filters in sidebar
+    with st.sidebar:
+        st.header("Map Filters")
+        
+        # Show/hide options - use session state values as defaults
+        show_deliveries = st.checkbox(
+            "Show Deliveries", 
+            value=st.session_state.map_filters.get('show_deliveries', True),
+            key="show_deliveries_checkbox"
+        )
+        st.session_state.map_filters['show_deliveries'] = show_deliveries
+        
+        show_depots = st.checkbox(
+            "Show Depots", 
+            value=st.session_state.map_filters.get('show_depots', True),
+            key="show_depots_checkbox"
+        )
+        st.session_state.map_filters['show_depots'] = show_depots
+        
+        # Show/hide data table
+        show_data_table = st.checkbox(
+            "Show Data Table", 
+            value=st.session_state.map_filters.get('show_data_table', False),
+            key="show_data_table_checkbox"
+        )
+        st.session_state.map_filters['show_data_table'] = show_data_table
+        
+        # Choose visualization tabs
+        show_calendar = st.checkbox(
+            "Show Calendar View", 
+            value=st.session_state.map_filters.get('show_calendar', True),
+            key="show_calendar_checkbox"
+        )
+        st.session_state.map_filters['show_calendar'] = show_calendar
+
+    # Try to load data
+    try:
+        # Get data paths
+        root_dir = Path(__file__).resolve().parent.parent.parent  # Go up to project root level
+        delivery_path = os.path.join(root_dir, 'data', 'delivery-data', 'delivery_data.csv')  # Fixed directory name with underscore
+        vehicle_path = os.path.join(root_dir, 'data', 'vehicle-data', 'vehicle_data.csv')    # Fixed directory name with underscore
+        
+        # Check if files exist
+        if not os.path.exists(delivery_path):
+            # Try with hyphen instead of underscore
+            delivery_path = os.path.join(root_dir, 'data', 'delivery-data', 'delivery_data.csv')
+            if not os.path.exists(delivery_path):
+                st.warning(f"Delivery data file not found at: {delivery_path}")
+                st.info("Please generate data first with: python src/utils/generate_all_data.py")
+                return
+            
+        if not os.path.exists(vehicle_path):
+            # Try with hyphen instead of underscore
+            vehicle_path = os.path.join(root_dir, 'data', 'vehicle-data', 'vehicle_data.csv')
+            if not os.path.exists(vehicle_path):
+                st.warning(f"Vehicle data file not found at: {vehicle_path}")
+                st.info("Please generate data first with: python src/utils/generate_all_data.py")
+                return
+            
+        # Load data
+        delivery_data = pd.read_csv(delivery_path)
+        vehicle_data = pd.read_csv(vehicle_path)
+        
+        # Ensure delivery_date is properly formatted as datetime
+        if 'delivery_date' in delivery_data.columns:
+            delivery_data['delivery_date'] = pd.to_datetime(delivery_data['delivery_date'])
+        
+        # Add more filters if data is available - CONVERT TO MULTI-SELECT
+        if 'priority' in delivery_data.columns:
+            with st.sidebar:
+                all_priorities = sorted(delivery_data['priority'].unique().tolist())
+                selected_priorities = st.multiselect(
+                    "Filter by Priority",
+                    options=all_priorities,
+                    default=st.session_state.map_filters.get('priority_filter', all_priorities),
+                    key="priority_multiselect"
+                )
+                st.session_state.map_filters['priority_filter'] = selected_priorities
+                
+                if selected_priorities:
+                    delivery_data = delivery_data[delivery_data['priority'].isin(selected_priorities)]
+        
+        if 'status' in delivery_data.columns:
+            with st.sidebar:
+                all_statuses = sorted(delivery_data['status'].unique().tolist())
+                selected_statuses = st.multiselect(
+                    "Filter by Status",
+                    options=all_statuses,
+                    default=st.session_state.map_filters.get('status_filter', all_statuses),
+                    key="status_multiselect"
+                )
+                st.session_state.map_filters['status_filter'] = selected_statuses
+                
+                if selected_statuses:
+                    delivery_data = delivery_data[delivery_data['status'].isin(selected_statuses)]
+        
+        if 'delivery_date' in delivery_data.columns:
+            with st.sidebar:
+                # Get the min/max dates from the ORIGINAL unfiltered data
+                # Load original data to get proper date range
+                original_data = pd.read_csv(delivery_path)
+                if 'delivery_date' in original_data.columns:
+                    original_data['delivery_date'] = pd.to_datetime(original_data['delivery_date'])
+                    
+                min_date = original_data['delivery_date'].min().date()
+                max_date = original_data['delivery_date'].max().date()
+                
+                # Get saved values from session state
+                saved_start_date = st.session_state.map_filters.get('date_range', [None, None])[0]
+                saved_end_date = st.session_state.map_filters.get('date_range', [None, None])[1]
+                
+                # Validate saved dates - ensure they're within allowed range
+                if saved_start_date and saved_start_date < min_date:
+                    saved_start_date = min_date
+                if saved_end_date and saved_end_date > max_date:
+                    saved_end_date = max_date
+                    
+                # Set default values with proper validation
+                default_start_date = saved_start_date if saved_start_date else min_date
+                default_end_date = saved_end_date if saved_end_date else min(min_date + timedelta(days=7), max_date)
+                
+                # Add date range picker
+                try:
+                    date_range = st.date_input(
+                        "Date Range",
+                        value=(default_start_date, default_end_date),
+                        min_value=min_date,
+                        max_value=max_date,
+                        key="date_range_input"
+                    )
+                    
+                    # Update session state with new date range
+                    if len(date_range) == 2:
+                        st.session_state.map_filters['date_range'] = list(date_range)
+                        start_date, end_date = date_range
+                        mask = (delivery_data['delivery_date'].dt.date >= start_date) & (delivery_data['delivery_date'].dt.date <= end_date)
+                        delivery_data = delivery_data[mask]
+                except Exception as e:
+                    # If there's any error with the date range, reset it
+                    st.error(f"Error with date range: {e}")
+                    st.session_state.map_filters['date_range'] = [min_date, max_date]
+                    date_range = (min_date, max_date)
+                    mask = (delivery_data['delivery_date'].dt.date >= min_date) & (delivery_data['delivery_date'].dt.date <= max_date)
+                    delivery_data = delivery_data[mask]
+                    
+        # MOVED STATISTICS TO THE TOP
+        st.subheader("Delivery Overview")
+        col1, col2, col3 = st.columns(3)
+        
+        with col1:
+            st.metric("Deliveries Shown", len(delivery_data))
+            
+        with col2:
+            if 'weight_kg' in delivery_data.columns:
+                total_weight = delivery_data['weight_kg'].sum()
+                st.metric("Total Weight", f"{total_weight:.2f} kg")
+                
+        with col3:
+            if 'status' in delivery_data.columns:
+                pending = len(delivery_data[delivery_data['status'] == 'Pending'])
+                st.metric("Pending Deliveries", pending)
+        
+        # Status count columns - dynamic based on available statuses
+        if 'status' in delivery_data.columns:
+            status_counts = delivery_data['status'].value_counts()
+            # Create a varying number of columns based on unique statuses
+            status_cols = st.columns(len(status_counts))
+            
+            for i, (status, count) in enumerate(status_counts.items()):
+                with status_cols[i]:
+                    # Choose color based on status
+                    delta_color = "normal"
+                    if status == "Delivered":
+                        delta_color = "off" 
+                    elif status == "In Transit":
+                        delta_color = "normal"
+                    elif status == "Pending":
+                        delta_color = "inverse"  # Red
+                    
+                    # Calculate percentage
+                    percentage = round((count / len(delivery_data)) * 100, 1)
+                    st.metric(
+                        f"{status}", 
+                        count,
+                        f"{percentage}% of total",
+                        delta_color=delta_color
+                    )
+        
+        # Create map
+        singapore_coords = [1.3521, 103.8198]  # Center of Singapore
+        m = folium.Map(location=singapore_coords, zoom_start=12)
+        
+        # Add delivery markers
+        if show_deliveries:
+            for _, row in delivery_data.iterrows():
+                # Create popup content
+                popup_content = f"<b>ID:</b> {row['delivery_id']}<br>"
+                
+                if 'customer_name' in row:
+                    popup_content += f"<b>Customer:</b> {row['customer_name']}<br>"
+                
+                if 'address' in row:
+                    popup_content += f"<b>Address:</b> {row['address']}<br>"
+                    
+                if 'time_window' in row:
+                    popup_content += f"<b>Time Window:</b> {row['time_window']}<br>"
+                    
+                if 'priority' in row:
+                    popup_content += f"<b>Priority:</b> {row['priority']}<br>"
+                    
+                if 'delivery_date' in row:
+                    popup_content += f"<b>Date:</b> {row['delivery_date'].strftime('%b %d, %Y')}<br>"
+                
+                if 'status' in row:
+                    popup_content += f"<b>Status:</b> {row['status']}<br>"
+            
+                # Choose marker color based on priority
+                color = 'blue'
+                if 'priority' in row:
+                    if row['priority'] == 'High':
+                        color = 'red'
+                    elif row['priority'] == 'Medium':
+                        color = 'orange'
+            
+                # Add marker to map
+                folium.Marker(
+                    [row['latitude'], row['longitude']],
+                    popup=folium.Popup(popup_content, max_width=300),
+                    tooltip=f"Delivery {row['delivery_id']}",
+                    icon=folium.Icon(color=color)
+                ).add_to(m)
+        
+        # Add depot markers
+        if show_depots:
+            for _, row in vehicle_data.iterrows():
+                # Create popup content
+                popup_content = f"<b>Vehicle ID:</b> {row['vehicle_id']}<br>"
+                
+                if 'vehicle_type' in row:
+                    popup_content += f"<b>Type:</b> {row['vehicle_type']}<br>"
+                    
+                if 'driver_name' in row:
+                    popup_content += f"<b>Driver:</b> {row['driver_name']}<br>"
+            
+                # Add marker to map
+                folium.Marker(
+                    [row['depot_latitude'], row['depot_longitude']],
+                    popup=folium.Popup(popup_content, max_width=300),
+                    tooltip=f"Depot: {row['vehicle_id']}",
+                    icon=folium.Icon(color='green', icon='home', prefix='fa')
+                ).add_to(m)
+        
+        # Display the map
+        folium_static(m, width=800, height=500)
+        
+        # Display calendar visualization if selected
+        if show_calendar and 'delivery_date' in delivery_data.columns and 'time_window' in delivery_data.columns:
+            st.subheader("Delivery Schedule Calendar")
+            
+            # Process data for calendar view
+            calendar_data = delivery_data.copy()
+            
+            # Extract start and end times from time_window
+            calendar_data[['start_time', 'end_time']] = calendar_data['time_window'].str.split('-', expand=True)
+            
+            # Create start and end datetime for each delivery
+            calendar_data['Start'] = pd.to_datetime(
+                calendar_data['delivery_date'].dt.strftime('%Y-%m-%d') + ' ' + calendar_data['start_time']
+            )
+            calendar_data['Finish'] = pd.to_datetime(
+                calendar_data['delivery_date'].dt.strftime('%Y-%m-%d') + ' ' + calendar_data['end_time']
+            )
+            
+            # Create task column for Gantt chart
+            calendar_data['Task'] = calendar_data['delivery_id'] + ': ' + calendar_data['customer_name']
+            
+            # Create color mapping for priority
+            if 'priority' in calendar_data.columns:
+                color_map = {'High': 'rgb(255, 0, 0)', 'Medium': 'rgb(255, 165, 0)', 'Low': 'rgb(0, 0, 255)'}
+                calendar_data['Color'] = calendar_data['priority'].map(color_map)
+            else:
+                calendar_data['Color'] = 'rgb(0, 0, 255)'  # Default blue
+            
+            # Get all available dates and add ƒmulti-select filter
+            all_dates = sorted(calendar_data['delivery_date'].dt.date.unique())
+
+            # Format dates for display in the dropdown
+            date_options = {date.strftime('%b %d, %Y'): date for date in all_dates}
+
+            # Get default selection from session state
+            default_selections = st.session_state.map_filters.get('calendar_selected_dates', [])
+
+            # Validate default selections - only keep dates that exist in current options
+            valid_default_selections = [date_str for date_str in default_selections if date_str in date_options.keys()]
+
+            # If no valid selections remain, default to first date (if available)
+            if not valid_default_selections and date_options:
+                valid_default_selections = [list(date_options.keys())[0]]
+
+            # Add multiselect for date filtering with validated defaults
+            selected_date_strings = st.multiselect(
+                "Select dates to display",
+                options=list(date_options.keys()),
+                default=valid_default_selections,
+                key="calendar_date_selector"
+            )
+
+            # Save selections to session state
+            st.session_state.map_filters['calendar_selected_dates'] = selected_date_strings
+
+            # Convert selected strings back to date objects
+            selected_dates = [date_options[date_str] for date_str in selected_date_strings]
+            
+            if not selected_dates:
+                st.info("Please select at least one date to view the delivery schedule.")
+            else:
+                # Filter calendar data to only include selected dates
+                filtered_calendar = calendar_data[calendar_data['delivery_date'].dt.date.isin(selected_dates)]
+                
+                # Group tasks by date for better visualization
+                date_groups = filtered_calendar.groupby(filtered_calendar['delivery_date'].dt.date)
+                
+                # Create tabs only for the selected dates
+                date_tabs = st.tabs([date.strftime('%b %d, %Y') for date in selected_dates])
+                
+                for i, (date, tab) in enumerate(zip(selected_dates, date_tabs)):
+                    with tab:
+                        # Filter data for this date
+                        day_data = filtered_calendar[filtered_calendar['delivery_date'].dt.date == date]
+                        
+                        if len(day_data) > 0:
+                            # Create figure
+                            fig = px.timeline(
+                                day_data, 
+                                x_start="Start", 
+                                x_end="Finish", 
+                                y="Task",
+                                color="priority" if 'priority' in day_data.columns else None,
+                                color_discrete_map={"High": "red", "Medium": "orange", "Low": "blue"},
+                                hover_data=["customer_name", "address", "weight_kg", "status"]
+                            )
+                            
+                            # Update layout
+                            fig.update_layout(
+                                title=f"Deliveries scheduled for {date.strftime('%b %d, %Y')}",
+                                xaxis_title="Time of Day",
+                                yaxis_title="Delivery",
+                                height=max(300, 50 * len(day_data)),
+                                yaxis={'categoryorder':'category ascending'}
+                            )
+                            
+                            # Display figure
+                            st.plotly_chart(fig, use_container_width=True)
+                            
+                            # Show summary
+                            col1, col2, col3 = st.columns(3)
+                            with col1:
+                                st.metric("Total Deliveries", len(day_data))
+                            with col2:
+                                if 'weight_kg' in day_data.columns:
+                                    st.metric("Total Weight", f"{day_data['weight_kg'].sum():.2f} kg")
+                            with col3:
+                                if 'priority' in day_data.columns and 'High' in day_data['priority'].values:
+                                    st.metric("High Priority", len(day_data[day_data['priority'] == 'High']))
+                            
+                            # NEW - Add delivery status breakdown for this day
+                            if 'status' in day_data.columns:
+                                st.write("##### Deliveries by Status")
+                                status_counts = day_data['status'].value_counts()
+                                status_cols = st.columns(min(4, len(status_counts)))
+                                
+                                for i, (status, count) in enumerate(status_counts.items()):
+                                    col_idx = i % len(status_cols)
+                                    with status_cols[col_idx]:
+                                        st.metric(status, count)
+                        else:
+                            st.info(f"No deliveries scheduled for {date.strftime('%b %d, %Y')}")
+        
+        # Display raw data table if selected
+        if show_data_table:
+            st.subheader("Delivery Data")
+            
+            # Create a copy for display
+            display_df = delivery_data.copy()
+            
+            # Convert delivery_date back to string for display
+            if 'delivery_date' in display_df.columns:
+                display_df['delivery_date'] = display_df['delivery_date'].dt.strftime('%b %d, %Y')
+            
+            # Compute which deliveries are urgent (next 7 days)
+            if 'delivery_date' in delivery_data.columns:
+                today = datetime.now().date()
+                next_week = today + timedelta(days=7)
+                
+                # Function to highlight rows based on delivery status and urgency
+                def highlight_rows(row):
+                    delivery_date = pd.to_datetime(row['delivery_date']).date() if 'delivery_date' in row else None
+                    
+                    # Check status first - highlight delivered rows in green
+                    if 'status' in row and row['status'] == 'Delivered':
+                        return ['background-color: rgba(0, 255, 0, 0.1)'] * len(row)
+                    # Then check for urgent high-priority deliveries - highlight in red
+                    elif delivery_date and delivery_date <= next_week and delivery_date >= today and row['priority'] == 'High':
+                        return ['background-color: rgba(255, 0, 0, 0.1)'] * len(row)
+                    else:
+                        return [''] * len(row)
+                
+                # Display styled dataframe
+                st.dataframe(display_df.style.apply(highlight_rows, axis=1))
+            else:
+                st.dataframe(display_df)
+
+    except Exception as e:
+        st.error(f"Error loading data: {str(e)}")
+        st.info("Please generate the data first by running: python src/utils/generate_all_data.py")
+        st.write("Error details:", e)  # Detailed error for debugging
+
+# Make the function executable when file is run directly
+if __name__ == "__main__":
+    # This is for debugging/testing the function independently
+    st.set_page_config(page_title="Map View - Delivery Route Optimization", page_icon="🗺️", layout="wide")
+    map_page()

src/pages/_optimize_page.py

@@ -0,0 +1,1781 @@
+import streamlit as st
+import pandas as pd
+import numpy as np
+import folium
+from streamlit_folium import folium_static
+import os
+from pathlib import Path
+from datetime import datetime, timedelta
+import matplotlib.pyplot as plt
+import random
+import time
+from ortools.constraint_solver import routing_enums_pb2
+from ortools.constraint_solver import pywrapcp
+import folium.plugins
+from folium.features import DivIcon
+import requests
+import plotly.express as px
+
+def clear_optimization_results():
+    """Clear optimization results when parameters change"""
+    if 'optimization_result' in st.session_state:
+        st.session_state.optimization_result = None
+
+def optimize_page():
+    """
+    Render the optimization page with controls for route optimization
+    """
+    st.title("Delivery Route Optimization")
+
+    # Add help section with expander
+    with st.expander("📚 How to Use This Page"):
+        st.markdown("""
+        ## Step-by-Step Guide to Route Optimization
+        
+        This application helps you optimize delivery routes by assigning deliveries to vehicles in the most efficient way possible. Follow these steps to get started:
+        
+        ### 1. Set Optimization Parameters (Sidebar)
+        
+        - **Select Delivery Dates**: Choose which dates to include in optimization. Select "All" to include all dates.
+        - **Priority Importance**: Higher values give more weight to high-priority deliveries.
+        - **Time Window Importance**: Higher values enforce stricter adherence to delivery time windows.
+        - **Load Balancing vs Distance**: Higher values distribute deliveries more evenly across vehicles.
+        - **Maximum Vehicles**: Set the maximum number of vehicles to use for deliveries.
+        - **Minimum Time Window Compliance**: Set the minimum percentage of deliveries that must be within their time windows.
+        
+        ### 2. Generate Routes
+        
+        - Review the delivery statistics and vehicle availability information
+        - Click the **Generate Optimal Routes** button to run the optimization algorithm
+        - The algorithm will assign deliveries to vehicles based on your parameters
+        
+        ### 3. Review Optimization Results
+        
+        - **Overall Performance**: Check metrics like assigned deliveries, vehicles used, and time window compliance
+        - **Time & Distance Distribution**: See how delivery workload is distributed across vehicles
+        - **Route Map**: Interactive map showing the optimized routes for each vehicle
+          - Use the date filter to show routes for specific days
+          - Hover over markers and routes for detailed information
+        - **Calendar View**: View delivery schedules organized by date
+          - Green bars indicate on-time deliveries
+          - Orange bars indicate late deliveries
+          - Red bars indicate unassigned deliveries
+        
+        ### 4. Adjust and Refine
+        
+        If the results don't meet your requirements:
+        
+        - **Not enough vehicles?** Increase the maximum vehicles allowed
+        - **Time windows not met?** Decrease the time window importance or minimum compliance
+        - **High priority deliveries not assigned?** Increase priority importance
+        - **Routes too unbalanced?** Increase load balancing parameter
+        
+        Remember to click **Generate Optimal Routes** after changing any parameters to see the updated results.
+        """)
+    
+    # Initialize session state variables
+    if 'optimization_result' not in st.session_state:
+        st.session_state.optimization_result = None
+    if 'optimization_params' not in st.session_state:
+        st.session_state.optimization_params = {
+            'priority_weight': 0.3,
+            'time_window_weight': 0.5,
+            'balance_weight': 0.2,
+            'max_vehicles': 5,
+            'selected_dates': ["All"]
+        }
+    if 'calendar_display_dates' not in st.session_state:
+        st.session_state.calendar_display_dates = None
+    # Add this new session state variable to store calculated road routes
+    if 'calculated_road_routes' not in st.session_state:
+        st.session_state.calculated_road_routes = {}
+    
+    # Load data
+    data = load_all_data()
+    if not data:
+        return
+    
+    delivery_data, vehicle_data, distance_matrix, time_matrix, locations = data
+    
+    # Optimization parameters
+    st.sidebar.header("Optimization Parameters")
+    
+    # Date selection for deliveries
+    if 'delivery_date' in delivery_data.columns:
+        available_dates = sorted(delivery_data['delivery_date'].unique())
+        date_options = ["All"] + list(available_dates)
+        
+        # Store current value before selection
+        current_selected_dates = st.session_state.optimization_params['selected_dates']
+        
+        selected_dates = st.sidebar.multiselect(
+            "Select Delivery Dates",
+            options=date_options,
+            default=current_selected_dates,
+            key="delivery_date_selector"
+        )
+        
+        # Check if selection changed
+        if selected_dates != current_selected_dates:
+            clear_optimization_results()
+            st.session_state.optimization_params['selected_dates'] = selected_dates
+            
+        # Handle filtering based on selection
+        if "All" not in selected_dates:
+            if selected_dates:  # If specific dates were selected
+                delivery_data = delivery_data[delivery_data['delivery_date'].isin(selected_dates)]
+            elif available_dates:  # No dates selected, show warning
+                st.sidebar.warning("No dates selected. Please select at least one delivery date.")
+                return
+        # If "All" is selected, keep all dates - no filtering needed
+    
+    # Priority weighting
+    current_priority = st.session_state.optimization_params['priority_weight']
+    priority_weight = st.sidebar.slider(
+        "Priority Importance",
+        min_value=0.0,
+        max_value=1.0,
+        value=current_priority,
+        help="Higher values give more importance to high-priority deliveries",
+        key="priority_weight",
+        on_change=clear_optimization_results
+    )
+
+    # Time window importance
+    current_time_window = st.session_state.optimization_params['time_window_weight']
+    time_window_weight = st.sidebar.slider(
+        "Time Window Importance",
+        min_value=0.0,
+        max_value=1.0,
+        value=current_time_window,
+        help="Higher values enforce stricter adherence to delivery time windows",
+        key="time_window_weight",
+        on_change=clear_optimization_results
+    )
+
+    # Distance vs load balancing
+    current_balance = st.session_state.optimization_params['balance_weight']
+    balance_weight = st.sidebar.slider(
+        "Load Balancing vs Distance",
+        min_value=0.0,
+        max_value=1.0,
+        value=current_balance,
+        help="Higher values prioritize even distribution of deliveries across vehicles over total distance",
+        key="balance_weight",
+        on_change=clear_optimization_results
+    )
+
+    # Max vehicles to use
+    available_vehicles = vehicle_data[vehicle_data['status'] == 'Available']
+    current_max_vehicles = st.session_state.optimization_params['max_vehicles']
+    max_vehicles = st.sidebar.slider(
+        "Maximum Vehicles to Use",
+        min_value=1,
+        max_value=len(available_vehicles),
+        value=min(current_max_vehicles, len(available_vehicles)),
+        key="max_vehicles",
+        on_change=clear_optimization_results
+    )
+
+    # Add minimum time window compliance slider
+    min_time_window_compliance = st.sidebar.slider(
+        "Minimum Time Window Compliance (%)",
+        min_value=0,
+        max_value=100,
+        value=75,
+        help="Minimum percentage of deliveries that must be within their time window",
+        key="min_time_window_compliance",
+        on_change=clear_optimization_results
+    )
+
+    # Update session state with new parameter values
+    st.session_state.optimization_params['priority_weight'] = priority_weight
+    st.session_state.optimization_params['time_window_weight'] = time_window_weight
+    st.session_state.optimization_params['balance_weight'] = balance_weight
+    st.session_state.optimization_params['max_vehicles'] = max_vehicles
+
+    # # Add a notification when parameters have changed and results need regenerating
+    # if ('optimization_result' not in st.session_state or st.session_state.optimization_result is None):
+    #     st.warning("⚠️ Optimization parameters have changed. Please click 'Generate Optimal Routes' to update results.")
+    
+    # Main optimization section
+    col1, col2 = st.columns([2, 1])
+    
+    with col1:
+        st.subheader("Delivery Route Optimizer")
+        
+        # Filter out completed deliveries for statistics
+        if 'status' in delivery_data.columns:
+            pending_deliveries = delivery_data[delivery_data['status'] != 'Delivered']
+            completed_count = len(delivery_data) - len(pending_deliveries)
+        else:
+            pending_deliveries = delivery_data
+            completed_count = 0
+            
+        st.write(f"Optimizing routes for {len(pending_deliveries)} pending deliveries using up to {max_vehicles} vehicles")
+        
+        # Statistics
+        st.write("#### Delivery Statistics")
+        total_count = len(delivery_data)
+        pending_count = len(pending_deliveries)
+        
+        col1a, col1b = st.columns(2)
+        with col1a:
+            st.metric("Total Deliveries", total_count)
+        with col1b:
+            st.metric("Pending Deliveries", pending_count, 
+                     delta=f"-{completed_count}" if completed_count > 0 else None,
+                     delta_color="inverse" if completed_count > 0 else "normal")
+        
+        if 'priority' in delivery_data.columns:
+            # Show priority breakdown for pending deliveries only
+            priority_counts = pending_deliveries['priority'].value_counts()
+            
+            # Display priority counts in a more visual way
+            st.write("##### Priority Breakdown")
+            priority_cols = st.columns(min(3, len(priority_counts)))
+            
+            for i, (priority, count) in enumerate(priority_counts.items()):
+                col_idx = i % len(priority_cols)
+                with priority_cols[col_idx]:
+                    st.metric(f"{priority}", count)
+        
+        if 'weight_kg' in delivery_data.columns:
+            # Calculate weight only for pending deliveries
+            total_weight = pending_deliveries['weight_kg'].sum()
+            st.metric("Total Weight (Pending)", f"{total_weight:.2f} kg")
+    
+    with col2:
+        st.write("#### Vehicle Availability")
+        st.write(f"Available Vehicles: {len(available_vehicles)}")
+        
+        # Show vehicle capacity
+        if 'max_weight_kg' in vehicle_data.columns:
+            total_capacity = available_vehicles['max_weight_kg'].sum()
+            st.write(f"Total Capacity: {total_capacity:.2f} kg")
+            
+            # Check if we have enough capacity
+            if 'weight_kg' in delivery_data.columns:
+                if total_capacity < total_weight:
+                    st.warning("⚠️ Insufficient vehicle capacity for all deliveries")
+                else:
+                    st.success("✅ Sufficient vehicle capacity")
+    
+    # Run optimization button
+    run_optimization_btn = st.button("Generate Optimal Routes")
+    
+    # Check if we should display results (either have results in session or button was clicked)
+    if run_optimization_btn or st.session_state.optimization_result is not None:
+        if run_optimization_btn:
+            # Run new optimization
+            with st.spinner("Calculating optimal routes..."):
+                start_time = time.time()
+                
+                # Filter out completed deliveries before optimization
+                if 'status' in delivery_data.columns:
+                    pending_deliveries = delivery_data[delivery_data['status'] != 'Delivered']
+                else:
+                    pending_deliveries = delivery_data
+                
+                # Prepare data for optimization - USE PENDING DELIVERIES ONLY
+                optimization_result = run_optimization(
+                    delivery_data=pending_deliveries,
+                    vehicle_data=available_vehicles.iloc[:max_vehicles],
+                    distance_matrix=distance_matrix,
+                    time_matrix=time_matrix,
+                    locations=locations,
+                    priority_weight=priority_weight,
+                    time_window_weight=time_window_weight,
+                    balance_weight=balance_weight,
+                    min_time_window_compliance=min_time_window_compliance/100.0  # Convert to decimal
+                )
+                
+                end_time = time.time()
+                st.success(f"Optimization completed in {end_time - start_time:.2f} seconds")
+                
+                # Store results in session state
+                st.session_state.optimization_result = optimization_result
+        else:
+            # Use existing results
+            optimization_result = st.session_state.optimization_result
+            
+        # Filter pending deliveries before displaying results    
+        if 'status' in delivery_data.columns:
+            pending_deliveries = delivery_data[delivery_data['status'] != 'Delivered']
+        else:
+            pending_deliveries = delivery_data
+            
+        # Display results with filtered pending deliveries
+        display_optimization_results(
+            optimization_result=optimization_result,
+            delivery_data=pending_deliveries,  # ← CHANGED: Use pending_deliveries instead
+            vehicle_data=available_vehicles.iloc[:max_vehicles],
+            distance_matrix=distance_matrix,
+            time_matrix=time_matrix,
+            locations=locations
+        )
+
+def load_all_data():
+    """
+    Load all necessary data for optimization
+    
+    Returns:
+        tuple of (delivery_data, vehicle_data, distance_matrix, time_matrix, locations)
+    """
+    # Get data paths
+    root_dir = Path(__file__).resolve().parent.parent.parent
+    delivery_path = os.path.join(root_dir, 'data', 'delivery-data', 'delivery_data.csv')
+    vehicle_path = os.path.join(root_dir, 'data', 'vehicle-data', 'vehicle_data.csv')
+    distance_matrix_path = os.path.join(root_dir, 'data', 'time-matrix', 'distance_matrix.csv')
+    time_matrix_path = os.path.join(root_dir, 'data', 'time-matrix', 'base_time_matrix.csv')
+    locations_path = os.path.join(root_dir, 'data', 'time-matrix', 'locations.csv')
+    
+    # Check if files exist
+    missing_files = []
+    for path, name in [
+        (delivery_path, "delivery data"),
+        (vehicle_path, "vehicle data"),
+        (distance_matrix_path, "distance matrix"),
+        (time_matrix_path, "time matrix"),
+        (locations_path, "locations data")
+    ]:
+        if not os.path.exists(path):
+            missing_files.append(name)
+    
+    if missing_files:
+        st.error(f"Missing required data: {', '.join(missing_files)}")
+        st.info("Please generate all data first by running: python src/utils/generate_all_data.py")
+        return None
+    
+    # Load data
+    delivery_data = pd.read_csv(delivery_path)
+    vehicle_data = pd.read_csv(vehicle_path)
+    distance_matrix = pd.read_csv(distance_matrix_path, index_col=0)
+    time_matrix = pd.read_csv(time_matrix_path, index_col=0)
+    locations = pd.read_csv(locations_path)
+    
+    return delivery_data, vehicle_data, distance_matrix, time_matrix, locations
+
+def run_optimization(delivery_data, vehicle_data, distance_matrix, time_matrix, locations, 
+                    priority_weight, time_window_weight, balance_weight, min_time_window_compliance=0.75):
+    """
+    Run the route optimization algorithm using Google OR-Tools
+    
+    Parameters:
+        delivery_data (pd.DataFrame): DataFrame containing delivery information
+        vehicle_data (pd.DataFrame): DataFrame containing vehicle information
+        distance_matrix (pd.DataFrame): Distance matrix between locations
+        time_matrix (pd.DataFrame): Time matrix between locations
+        locations (pd.DataFrame): DataFrame with location details
+        priority_weight (float): Weight for delivery priority in optimization (α)
+        time_window_weight (float): Weight for time window adherence (β)
+        balance_weight (float): Weight for balancing load across vehicles (γ)
+        min_time_window_compliance (float): Minimum required time window compliance (δ)
+        
+    Returns:
+        dict: Optimization results
+    """
+    st.write("Setting up optimization model with OR-Tools...")
+    
+    # Extract required data for optimization
+    num_vehicles = len(vehicle_data)
+    num_deliveries = len(delivery_data)
+    
+    # Create a list of all locations (depots + delivery points)
+    all_locations = []
+    delivery_locations = []
+    depot_locations = []
+    vehicle_capacities = []
+    
+    # First, add depot locations (one per vehicle)
+    for i, (_, vehicle) in enumerate(vehicle_data.iterrows()):
+        depot_loc = {
+            'id': vehicle['vehicle_id'],
+            'type': 'depot',
+            'index': i,  # Important for mapping to OR-Tools indices
+            'latitude': vehicle['depot_latitude'],
+            'longitude': vehicle['depot_longitude'],
+            'vehicle_index': i
+        }
+        depot_locations.append(depot_loc)
+        all_locations.append(depot_loc)
+        
+        # Add vehicle capacity
+        if 'max_weight_kg' in vehicle:
+            vehicle_capacities.append(int(vehicle['max_weight_kg'] * 100))  # Convert to integers (OR-Tools works better with integers)
+        else:
+            vehicle_capacities.append(1000)  # Default capacity of 10kg (1000 in scaled units)
+    
+    # Then add delivery locations
+    for i, (_, delivery) in enumerate(delivery_data.iterrows()):
+        # Determine priority factor (will be used in the objective function)
+        priority_factor = 1.0
+        if 'priority' in delivery:
+            if delivery['priority'] == 'High':
+                priority_factor = 0.5  # Higher priority = lower cost
+            elif delivery['priority'] == 'Low':
+                priority_factor = 2.0  # Lower priority = higher cost
+        
+        # Calculate delivery demand (weight)
+        demand = int(delivery.get('weight_kg', 1.0) * 100)  # Convert to integers
+        
+        delivery_loc = {
+            'id': delivery['delivery_id'],
+            'type': 'delivery',
+            'index': num_vehicles + i,  # Important for mapping to OR-Tools indices
+            'latitude': delivery['latitude'],
+            'longitude': delivery['longitude'],
+            'priority': delivery.get('priority', 'Medium'),
+            'priority_factor': priority_factor,
+            'weight_kg': delivery.get('weight_kg', 1.0),
+            'demand': demand,
+            'time_window': delivery.get('time_window', '09:00-17:00'),
+            'customer_name': delivery.get('customer_name', 'Unknown')
+        }
+        delivery_locations.append(delivery_loc)
+        all_locations.append(delivery_loc)
+    
+    # Create distance and time matrices for OR-Tools
+    dist_matrix = np.zeros((len(all_locations), len(all_locations)))
+    time_matrix_mins = np.zeros((len(all_locations), len(all_locations)))
+    
+    # Use the provided distance_matrix if it's the right size, otherwise compute distances
+    if isinstance(distance_matrix, pd.DataFrame) and len(distance_matrix) == len(all_locations):
+        # Convert dataframe to numpy array
+        dist_matrix = distance_matrix.values
+        time_matrix_mins = time_matrix.values
+    else:
+        # Compute simple Euclidean distances (this is a fallback)
+        for i in range(len(all_locations)):
+            for j in range(len(all_locations)):
+                if i == j:
+                    continue
+                
+                # Approximate distance in km (very rough)
+                lat1, lon1 = all_locations[i]['latitude'], all_locations[i]['longitude']
+                lat2, lon2 = all_locations[j]['latitude'], all_locations[j]['longitude']
+                
+                # Simple Euclidean distance (for demo purposes)
+                dist = ((lat1 - lat2) ** 2 + (lon1 - lon2) ** 2) ** 0.5 * 111  # Convert to km
+                dist_matrix[i, j] = dist
+                time_matrix_mins[i, j] = dist * 2  # Rough estimate: 30km/h -> 2 mins per km
+    
+    # Prepare demand array (0 for depots, actual demand for deliveries)
+    demands = [0] * num_vehicles + [d['demand'] for d in delivery_locations]
+    
+    # Calculate total weight of all deliveries
+    total_delivery_weight = sum(d['demand'] for d in delivery_locations)
+    
+    # OR-Tools setup
+    # Create the routing index manager
+    manager = pywrapcp.RoutingIndexManager(
+        len(all_locations),  # Number of nodes (depots + deliveries)
+        num_vehicles,        # Number of vehicles
+        list(range(num_vehicles)),  # Vehicle start nodes (depot indices)
+        list(range(num_vehicles))   # Vehicle end nodes (back to depots)
+    )
+    
+    # Create Routing Model
+    routing = pywrapcp.RoutingModel(manager)
+    
+    # Define distance callback with priority weighting
+    # This implements the objective function: min sum_{i,j,k} c_jk * x_ijk * p_k^α
+    def distance_callback(from_index, to_index):
+        """Returns the weighted distance between the two nodes."""
+        # Convert from routing variable Index to distance matrix NodeIndex
+        from_node = manager.IndexToNode(from_index)
+        to_node = manager.IndexToNode(to_index)
+        
+        # Get base distance
+        base_distance = int(dist_matrix[from_node, to_node] * 1000)  # Convert to integers
+        
+        # Apply priority weighting to destination node (if it's a delivery)
+        if to_node >= num_vehicles:  # It's a delivery node
+            delivery_idx = to_node - num_vehicles
+            # Apply the priority factor with the priority weight (α)
+            priority_factor = delivery_locations[delivery_idx]['priority_factor']
+            # Higher priority_weight = stronger effect of priority on cost
+            priority_multiplier = priority_factor ** priority_weight
+            return int(base_distance * priority_multiplier)
+        
+        return base_distance
+    
+    # Define time callback
+    def time_callback(from_index, to_index):
+        """Returns the travel time between the two nodes."""
+        # Convert from routing variable Index to time matrix NodeIndex
+        from_node = manager.IndexToNode(from_index)
+        to_node = manager.IndexToNode(to_index)
+        return int(time_matrix_mins[from_node, to_node] * 60)  # Convert minutes to seconds (integers)
+    
+    # Define service time callback - time spent at each delivery
+    def service_time_callback(from_index):
+        """Returns the service time for the node."""
+        # Service time is 0 for depots and 10 minutes (600 seconds) for deliveries
+        node_idx = manager.IndexToNode(from_index)
+        if node_idx >= num_vehicles:  # It's a delivery node
+            return 600  # 10 minutes in seconds
+        return 0  # No service time for depots
+    
+    # Define demand callback
+    def demand_callback(from_index):
+        """Returns the demand of the node."""
+        # Convert from routing variable Index to demands array
+        from_node = manager.IndexToNode(from_index)
+        return demands[from_node]
+    
+    # Register callbacks
+    transit_callback_index = routing.RegisterTransitCallback(distance_callback)
+    time_callback_index = routing.RegisterTransitCallback(time_callback)
+    service_callback_index = routing.RegisterUnaryTransitCallback(service_time_callback)
+    demand_callback_index = routing.RegisterUnaryTransitCallback(demand_callback)
+    
+    # Set the arc cost evaluator for all vehicles - this is our objective function
+    routing.SetArcCostEvaluatorOfAllVehicles(transit_callback_index)
+    
+    # Add capacity dimension - Hard Constraint 2: Vehicle Capacity Limits
+    routing.AddDimensionWithVehicleCapacity(
+        demand_callback_index,
+        0,                   # null capacity slack
+        vehicle_capacities,  # vehicle maximum capacities
+        True,                # start cumul to zero
+        'Capacity'
+    )
+    
+    capacity_dimension = routing.GetDimensionOrDie('Capacity')
+    
+    # Add load balancing penalties - Soft Constraint 3: Load Balancing Penalties
+    if balance_weight > 0.01:
+        # Calculate target weight per vehicle (ideal balanced load)
+        target_weight = total_delivery_weight / len(vehicle_capacities)
+        
+        for i in range(num_vehicles):
+            # Get vehicle capacity
+            vehicle_capacity = vehicle_capacities[i]
+            
+            # Set penalties for deviating from balanced load
+            # Scale penalty based on the balance_weight parameter (γ)
+            balance_penalty = int(10000 * balance_weight)
+            
+            # Add soft bounds around the target weight
+            # Lower bound: Don't penalize for being under the target if there's not enough weight
+            lower_target = max(0, int(target_weight * 0.8))
+            capacity_dimension.SetCumulVarSoftLowerBound(
+                routing.End(i), lower_target, balance_penalty
+            )
+            
+            # Upper bound: Penalize for going over the target
+            # But allow using more capacity if necessary to assign all deliveries
+            upper_target = min(vehicle_capacity, int(target_weight * 1.2))
+            capacity_dimension.SetCumulVarSoftUpperBound(
+                routing.End(i), upper_target, balance_penalty
+            )
+    
+    # Add time dimension with service times
+    # This implements Hard Constraint 5: Time Continuity and 
+    # Hard Constraint 6: Maximum Route Duration
+    routing.AddDimension(
+        time_callback_index,
+        60 * 60,       # Allow waiting time of 60 mins
+        24 * 60 * 60,  # Maximum time per vehicle (24 hours in seconds) - Hard Constraint 6
+        False,         # Don't force start cumul to zero
+        'Time'
+    )
+    time_dimension = routing.GetDimensionOrDie('Time')
+    
+    # Add service time to each node's visit duration
+    for node_idx in range(len(all_locations)):
+        index = manager.NodeToIndex(node_idx)
+        time_dimension.SetCumulVarSoftUpperBound(
+            index, 
+            24 * 60 * 60,  # 24 hours in seconds
+            1000000  # High penalty for violating the 24-hour constraint
+        )
+        time_dimension.SlackVar(index).SetValue(0)
+    
+    # Store time window variables to track compliance
+    time_window_vars = []
+    compliance_threshold = int(min_time_window_compliance * num_deliveries)
+    
+    # Add time window constraints - Hard Constraint 7: Time Window Compliance
+    if time_window_weight > 0.01:
+        # Create binary variables to track time window compliance
+        for delivery_idx, delivery in enumerate(delivery_locations):
+            if 'time_window' in delivery and delivery['time_window']:
+                try:
+                    start_time_str, end_time_str = delivery['time_window'].split('-')
+                    start_hour, start_min = map(int, start_time_str.split(':'))
+                    end_hour, end_min = map(int, end_time_str.split(':'))
+                    
+                    # Convert to seconds since midnight
+                    start_time_sec = (start_hour * 60 + start_min) * 60
+                    end_time_sec = (end_hour * 60 + end_min) * 60
+                    
+                    # Get the node index
+                    index = manager.NodeToIndex(num_vehicles + delivery_idx)
+                    
+                    # Add soft upper bound penalty with very high weight for late deliveries
+                    # This implements Soft Constraint 2: Time Window Penalties
+                    time_dimension.SetCumulVarSoftUpperBound(
+                        index, 
+                        end_time_sec, 
+                        int(1000000 * time_window_weight)  # High penalty for being late
+                    )
+                    
+                    # Don't penalize for early deliveries, just wait
+                    time_dimension.CumulVar(index).SetMin(start_time_sec)
+                    
+                    # Track this time window for compliance calculation
+                    time_window_vars.append((index, start_time_sec, end_time_sec))
+                except:
+                    # Skip if time window format is invalid
+                    pass
+    
+    # Hard Constraint 1: All Deliveries Must Be Assigned
+    # This is enforced by not creating disjunctions with penalties, but instead making all nodes mandatory
+    
+    # Hard Constraint 3: Flow Conservation (Route Continuity) is inherently enforced by OR-Tools
+    
+    # Hard Constraint 4: Start and End at Assigned Depots is enforced by the RoutingIndexManager setup
+    
+    # Set parameters for the solver
+    search_parameters = pywrapcp.DefaultRoutingSearchParameters()
+    
+    # Use guided local search to find good solutions
+    search_parameters.local_search_metaheuristic = (
+        routing_enums_pb2.LocalSearchMetaheuristic.GUIDED_LOCAL_SEARCH
+    )
+    
+    # Use path cheapest arc with resource constraints as the first solution strategy
+    search_parameters.first_solution_strategy = (
+        routing_enums_pb2.FirstSolutionStrategy.PATH_CHEAPEST_ARC
+    )
+    
+    # Give the solver enough time to find a good solution
+    search_parameters.time_limit.seconds = 10
+    
+    # Enable logging
+    search_parameters.log_search = True
+    
+    # Try to enforce the time window compliance threshold
+    if compliance_threshold > 0:
+        # First try to solve with all deliveries required
+        routing.CloseModelWithParameters(search_parameters)
+        
+        # Solve the problem
+        st.write(f"Solving optimization model with {num_deliveries} deliveries and {num_vehicles} vehicles...")
+        st.write(f"Target: At least {compliance_threshold} of {num_deliveries} deliveries ({min_time_window_compliance*100:.0f}%) must be within time windows")
+        
+        solution = routing.SolveWithParameters(search_parameters)
+    else:
+        # If no time window compliance required, solve normally
+        solution = routing.SolveWithParameters(search_parameters)
+    
+    # If no solution was found, try a relaxed version (allow some deliveries to be unassigned)
+    if not solution:
+        st.warning("Could not find a solution with all deliveries assigned. Trying a relaxed version...")
+        
+        # Create a new model with disjunctions to allow dropping some deliveries with high penalties
+        routing = pywrapcp.RoutingModel(manager)
+        
+        # Re-register callbacks
+        transit_callback_index = routing.RegisterTransitCallback(distance_callback)
+        time_callback_index = routing.RegisterTransitCallback(time_callback)
+        service_callback_index = routing.RegisterUnaryTransitCallback(service_time_callback)
+        demand_callback_index = routing.RegisterUnaryTransitCallback(demand_callback)
+        
+        routing.SetArcCostEvaluatorOfAllVehicles(transit_callback_index)
+        
+        # Add capacity dimension again
+        routing.AddDimensionWithVehicleCapacity(
+            demand_callback_index,
+            0, vehicle_capacities, True, 'Capacity'
+        )
+        
+        # Add time dimension again
+        routing.AddDimension(
+            time_callback_index,
+            60 * 60, 24 * 60 * 60, False, 'Time'
+        )
+        time_dimension = routing.GetDimensionOrDie('Time')
+        
+        # Add disjunctions with very high penalties to try to include all deliveries
+        for delivery_idx in range(num_deliveries):
+            index = manager.NodeToIndex(num_vehicles + delivery_idx)
+            routing.AddDisjunction([index], 1000000)  # High penalty but allows dropping if necessary
+        
+        # Try to solve with relaxed constraints
+        search_parameters.time_limit.seconds = 15  # Give more time for relaxed version
+        solution = routing.SolveWithParameters(search_parameters)
+        
+        if not solution:
+            st.error("Could not find any solution. Try increasing the number of vehicles or relaxing other constraints.")
+            return {
+                'routes': {},
+                'stats': {},
+                'parameters': {
+                    'priority_weight': priority_weight,
+                    'time_window_weight': time_window_weight,
+                    'balance_weight': balance_weight,
+                    'min_time_window_compliance': min_time_window_compliance
+                }
+            }
+    
+    # Extract solution
+    optimized_routes = {}
+    route_stats = {}
+    
+    if solution:
+        st.success("Solution found!")
+        
+        total_time_window_compliance = 0
+        total_deliveries_assigned = 0
+        
+        for vehicle_idx in range(num_vehicles):
+            route = []
+            vehicle_id = vehicle_data.iloc[vehicle_idx]['vehicle_id']
+            
+            # Get the vehicle information
+            vehicle_info = {
+                'id': vehicle_id,
+                'type': vehicle_data.iloc[vehicle_idx].get('vehicle_type', 'Standard'),
+                'capacity': vehicle_data.iloc[vehicle_idx].get('max_weight_kg', 1000),
+                'depot_latitude': vehicle_data.iloc[vehicle_idx]['depot_latitude'],
+                'depot_longitude': vehicle_data.iloc[vehicle_idx]['depot_longitude']
+            }
+            
+            # Initialize variables for tracking
+            index = routing.Start(vehicle_idx)
+            total_distance = 0
+            total_time = 0
+            total_load = 0
+            time_window_compliant = 0
+            total_deliveries = 0
+            
+            # Initialize variables to track current position and time
+            current_time_sec = 8 * 3600  # Start at 8:00 AM (8 hours * 3600 seconds)
+            
+            while not routing.IsEnd(index):
+                # Get the node index in the original data
+                node_idx = manager.IndexToNode(index)
+                
+                # Skip depot nodes (they're already at the start)
+                if node_idx >= num_vehicles:
+                    # This is a delivery node - get the corresponding delivery
+                    delivery_idx = node_idx - num_vehicles
+                    delivery = delivery_locations[delivery_idx].copy()  # Create a copy to modify
+                    
+                    # Calculate estimated arrival time in minutes since start of day
+                    arrival_time_sec = solution.Min(time_dimension.CumulVar(index))
+                    arrival_time_mins = arrival_time_sec // 60
+                    
+                    # Store the estimated arrival time in the delivery
+                    delivery['estimated_arrival'] = arrival_time_mins
+                    
+                    # Check time window compliance
+                    if 'time_window' in delivery and delivery['time_window']:
+                        try:
+                            start_time_str, end_time_str = delivery['time_window'].split('-')
+                            start_hour, start_min = map(int, start_time_str.split(':'))
+                            end_hour, end_min = map(int, end_time_str.split(':'))
+                            
+                            # Convert to minutes for comparison
+                            start_mins = start_hour * 60 + start_min
+                            end_mins = end_hour * 60 + end_min
+                            
+                            # Check if delivery is within time window
+                            on_time = False
+                            
+                            # If arrival <= end_time, consider it on-time (including early arrivals)
+                            if arrival_time_mins <= end_mins:
+                                on_time = True
+                                time_window_compliant += 1
+                                total_time_window_compliance += 1
+                            
+                            delivery['within_time_window'] = on_time
+                        except Exception as e:
+                            st.warning(f"Error parsing time window for delivery {delivery['id']}: {str(e)}")
+                            delivery['within_time_window'] = False
+                    
+                    # Add to route
+                    route.append(delivery)
+                    total_deliveries += 1
+                    total_deliveries_assigned += 1
+                    
+                    # Add to total load
+                    total_load += delivery['demand'] / 100  # Convert back to original units
+                
+                # Move to the next node
+                previous_idx = index
+                index = solution.Value(routing.NextVar(index))
+                
+                # Add distance and time from previous to current
+                if not routing.IsEnd(index):
+                    previous_node = manager.IndexToNode(previous_idx)
+                    next_node = manager.IndexToNode(index)
+                    
+                    # Add distance between these points
+                    segment_distance = dist_matrix[previous_node, next_node]
+                    total_distance += segment_distance
+                    
+                    # Add travel time between these points
+                    segment_time_sec = int(time_matrix_mins[previous_node, next_node] * 60)
+                    total_time += segment_time_sec / 60  # Convert seconds back to minutes
+            
+            # Store the route if it's not empty
+            if route:
+                optimized_routes[vehicle_id] = route
+                
+                # Calculate time window compliance percentage
+                time_window_percent = (time_window_compliant / total_deliveries * 100) if total_deliveries > 0 else 0
+                
+                # Store route statistics
+                route_stats[vehicle_id] = {
+                    'vehicle_type': vehicle_info['type'],
+                    'capacity_kg': vehicle_info['capacity'],
+                    'deliveries': len(route),
+                    'total_distance_km': round(total_distance, 2),
+                    'estimated_time_mins': round(total_time),
+                    'total_load_kg': round(total_load, 2),
+                    'time_window_compliant': time_window_compliant,
+                    'time_window_compliance': time_window_percent
+                }
+        
+        # Check if overall time window compliance meets the minimum requirement
+        overall_compliance = 0
+        if total_deliveries_assigned > 0:
+            overall_compliance = (total_time_window_compliance / total_deliveries_assigned)
+            
+        if overall_compliance < min_time_window_compliance:
+            st.warning(f"Solution found, but time window compliance ({overall_compliance*100:.1f}%) is below the minimum required ({min_time_window_compliance*100:.0f}%).")
+            st.info("Consider adjusting parameters: increase the number of vehicles, reduce the minimum compliance requirement, or adjust time window importance.")
+        else:
+            st.success(f"Solution meets time window compliance requirement: {overall_compliance*100:.1f}% (minimum required: {min_time_window_compliance*100:.0f}%)")
+    else:
+        st.error("No solution found. Try adjusting the parameters.")
+        optimized_routes = {}
+        route_stats = {}
+    
+    return {
+        'routes': optimized_routes,
+        'stats': route_stats,
+        'parameters': {
+            'priority_weight': priority_weight,
+            'time_window_weight': time_window_weight,
+            'balance_weight': balance_weight,
+            'min_time_window_compliance': min_time_window_compliance
+        }
+    }
+
+def display_optimization_results(optimization_result, delivery_data, vehicle_data, 
+                               distance_matrix, time_matrix, locations):
+    """
+    Display the optimization results
+    
+    Parameters:
+        optimization_result (dict): Result from the optimization algorithm
+        delivery_data (pd.DataFrame): Delivery information
+        vehicle_data (pd.DataFrame): Vehicle information
+        distance_matrix (pd.DataFrame): Distance matrix between locations
+        time_matrix (pd.DataFrame): Time matrix between locations
+        locations (pd.DataFrame): Location details
+    """
+    # Define colors for vehicle routes
+    colors = ['blue', 'red', 'green', 'purple', 'orange', 'darkblue', 
+              'darkred', 'darkgreen', 'cadetblue', 'darkpurple', 'pink', 
+              'lightblue', 'lightred', 'lightgreen', 'gray', 'black', 'lightgray']
+    
+    routes = optimization_result['routes']
+    
+    # Display summary statistics
+    st.subheader("Optimization Results")
+
+    # Calculate overall statistics
+    total_deliveries = sum(len(route) for route in routes.values())
+    active_vehicles = sum(1 for route in routes.values() if len(route) > 0)
+
+    # Calculate additional metrics
+    total_distance = sum(stats.get('total_distance_km', 0) for stats in optimization_result.get('stats', {}).values())
+    total_time_mins = sum(stats.get('estimated_time_mins', 0) for stats in optimization_result.get('stats', {}).values())
+
+    # Calculate time window compliance (on-time percentage)
+    on_time_deliveries = 0
+    total_route_deliveries = 0
+
+    # Count deliveries within time window
+    for vehicle_id, route in routes.items():
+        stats = optimization_result.get('stats', {}).get(vehicle_id, {})
+        
+        # Only process if we have stats for this vehicle
+        if stats and 'time_window_compliant' in stats:
+            # Use the actual count of compliant deliveries, not the percentage
+            on_time_deliveries += stats['time_window_compliant']
+        else:
+            # Try to estimate based on delivery details
+            for delivery in route:
+                if 'time_window' in delivery and 'estimated_arrival' in delivery:
+                    # Format is typically "HH:MM-HH:MM"
+                    try:
+                        time_window = delivery['time_window']
+                        start_time_str, end_time_str = time_window.split('-')
+                        
+                        # Convert to minutes for comparison
+                        start_mins = int(start_time_str.split(':')[0]) * 60 + int(start_time_str.split(':')[1])
+                        end_mins = int(end_time_str.split(':')[0]) * 60 + int(end_time_str.split(':')[1])
+                        arrival_mins = delivery.get('estimated_arrival', 0)
+                        
+                        # Only consider deliveries late if they arrive after the end time
+                        if arrival_mins <= end_mins:
+                            on_time_deliveries += 1
+                    except:
+                        pass
+        
+        total_route_deliveries += len(route)
+
+    # Ensure we have a valid number for on-time percentage
+    delivery_ontime_percent = 0
+    if total_route_deliveries > 0:
+        delivery_ontime_percent = (on_time_deliveries / total_route_deliveries) * 100
+
+    # Display metrics in a nicer layout with columns
+    st.write("### Overall Performance")
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        st.metric("Deliveries Assigned", f"{total_deliveries}/{len(delivery_data)}")
+        st.metric("Vehicles Used", f"{active_vehicles}/{len(vehicle_data)}")
+
+    with col2:
+        st.metric("Total Distance", f"{total_distance:.1f} km")
+        st.metric("Total Time", f"{int(total_time_mins//60)}h {int(total_time_mins%60)}m")
+
+    with col3:
+        st.metric("Time Window Compliance", f"{delivery_ontime_percent:.0f}%")
+        
+        # Calculate route efficiency (meters per delivery)
+        if total_deliveries > 0:
+            efficiency = (total_distance * 1000) / total_deliveries
+            st.metric("Avg Distance per Delivery", f"{efficiency:.0f} m")
+
+    # Add a visualization of time distribution
+    st.write("### Time & Distance Distribution by Vehicle")
+    time_data = {vehicle_id: stats.get('estimated_time_mins', 0) 
+                 for vehicle_id, stats in optimization_result.get('stats', {}).items()
+                 if len(routes.get(vehicle_id, [])) > 0}
+
+    if time_data:
+        # Create bar charts for time and distance
+        time_df = pd.DataFrame({
+            'Vehicle': list(time_data.keys()),
+            'Time (mins)': list(time_data.values())
+        })
+        
+        distance_data = {vehicle_id: stats.get('total_distance_km', 0) 
+                         for vehicle_id, stats in optimization_result.get('stats', {}).items()
+                         if len(routes.get(vehicle_id, [])) > 0}
+        
+        distance_df = pd.DataFrame({
+            'Vehicle': list(distance_data.keys()),
+            'Distance (km)': list(distance_data.values())
+        })
+        
+        col1, col2 = st.columns(2)
+        with col1:
+            st.bar_chart(time_df.set_index('Vehicle'))
+        with col2:
+            st.bar_chart(distance_df.set_index('Vehicle'))
+    
+    # Display the map with all routes
+    st.subheader("Route Map with Road Navigation")
+
+    # Add info about the route visualization
+    st.info("""
+    The map shows delivery routes that follow road networks from the depot to each stop in sequence, and back to the depot.
+    Numbered circles indicate the stop sequence, and arrows show travel direction.
+    """)
+    
+    # Extract all available dates from the delivery data
+    if 'delivery_date' in delivery_data.columns:
+        # Extract unique dates, ensuring all are converted to datetime objects
+        available_dates = sorted(pd.to_datetime(delivery_data['delivery_date'].unique()))
+        
+        # Format dates for display
+        date_options = {}
+        for date in available_dates:
+            # Ensure date is a proper datetime object before formatting
+            if isinstance(date, str):
+                date_obj = pd.to_datetime(date)
+            else:
+                date_obj = date
+            # Create the formatted string key
+            date_str = date_obj.strftime('%b %d, %Y')
+            date_options[date_str] = date_obj
+        
+        # Default to earliest date
+        default_date = min(available_dates) if available_dates else None
+        default_date_str = default_date.strftime('%b %d, %Y') if default_date else None
+        
+        # Create date selection dropdown
+        selected_date_str = st.selectbox(
+            "Select date to show routes for:",
+            options=list(date_options.keys()),
+            index=0 if default_date_str else None,
+        )
+        
+        # Convert selected string back to date object
+        selected_date = date_options[selected_date_str] if selected_date_str else None
+        
+        # Filter routes to only show deliveries for the selected date
+        if selected_date is not None:
+            filtered_routes = {}
+            
+            for vehicle_id, route in routes.items():
+                # Keep only deliveries for the selected date
+                filtered_route = []
+                
+                for delivery in route:
+                    delivery_id = delivery['id']
+                    # Find the delivery in the original data to get its date
+                    delivery_row = delivery_data[delivery_data['delivery_id'] == delivery_id]
+                    
+                    if not delivery_row.empty and 'delivery_date' in delivery_row:
+                        delivery_date = delivery_row['delivery_date'].iloc[0]
+                        
+                        # Check if this delivery is for the selected date
+                        if pd.to_datetime(delivery_date).date() == pd.to_datetime(selected_date).date():
+                            filtered_route.append(delivery)
+                
+                # Only add the vehicle if it has deliveries on this date
+                if filtered_route:
+                    filtered_routes[vehicle_id] = filtered_route
+            
+            # Replace the original routes with filtered ones for map display
+            routes_for_map = filtered_routes
+            st.write(f"Showing routes for {len(routes_for_map)} vehicles on {selected_date_str}")
+        else:
+            routes_for_map = routes
+    else:
+        routes_for_map = routes
+        st.warning("No delivery dates available in data. Showing all routes.")
+    
+    # Create a map centered on Singapore
+    singapore_coords = [1.3521, 103.8198]
+    m = folium.Map(location=singapore_coords, zoom_start=12)
+    
+    # Modify loop to use routes_for_map instead of routes
+    # Count total route segments for progress bar
+    total_segments = sum(len(route) + 1 for route in routes_for_map.values() if route)  # +1 for return to depot
+
+    # Create a unique key for this optimization result to use in session state
+    optimization_key = hash(str(optimization_result))
+
+    # Check if we have stored routes for this optimization result
+    if optimization_key not in st.session_state.calculated_road_routes:
+        # Initialize storage for this optimization
+        st.session_state.calculated_road_routes[optimization_key] = {}
+
+    # Count total route segments for progress bar
+    total_segments = sum(len(route) + 1 for route in routes_for_map.values() if route)  # +1 for return to depot
+    route_progress = st.progress(0)
+    progress_container = st.empty()
+    progress_container.text("Calculating routes: 0%")
+
+    # Counter for processed segments
+    processed_segments = 0
+
+    for i, (vehicle_id, route) in enumerate(routes_for_map.items()):
+        if not route:
+            continue
+        
+        # Get vehicle info
+        vehicle_info = vehicle_data[vehicle_data['vehicle_id'] == vehicle_id].iloc[0]
+        
+        # Use color cycling if we have more vehicles than colors
+        color = colors[i % len(colors)]
+        
+        # Add depot marker
+        depot_lat, depot_lon = vehicle_info['depot_latitude'], vehicle_info['depot_longitude']
+        
+        # Create depot popup content
+        depot_popup = f"""
+            <b>Depot:</b> {vehicle_id}<br>
+            <b>Vehicle Type:</b> {vehicle_info['vehicle_type']}<br>
+            <b>Driver:</b> {vehicle_info.get('driver_name', 'Unknown')}<br>
+        """
+        
+        # Add depot marker with START label
+        folium.Marker(
+            [depot_lat, depot_lon],
+            popup=folium.Popup(depot_popup, max_width=300),
+            tooltip=f"Depot: {vehicle_id} (START/END)",
+            icon=folium.Icon(color=color, icon='home', prefix='fa')
+        ).add_to(m)
+        
+        # Create route points for complete journey
+        waypoints = [(depot_lat, depot_lon)]  # Start at depot
+        
+        # Add all delivery locations as waypoints
+        for delivery in route:
+            waypoints.append((delivery['latitude'], delivery['longitude']))
+        
+        # Close the loop back to depot
+        waypoints.append((depot_lat, depot_lon))
+        
+        # Add delivery point markers with sequenced numbering
+        for j, delivery in enumerate(route):
+            lat, lon = delivery['latitude'], delivery['longitude']
+            
+            # Create popup content
+            popup_content = f"""
+                <b>Stop {j+1}:</b> {delivery['id']}<br>
+                <b>Customer:</b> {delivery.get('customer_name', 'Unknown')}<br>
+            """
+            
+            if 'priority' in delivery:
+                popup_content += f"<b>Priority:</b> {delivery['priority']}<br>"
+                
+            if 'weight_kg' in delivery:
+                popup_content += f"<b>Weight:</b> {delivery['weight_kg']:.2f} kg<br>"
+                
+            if 'time_window' in delivery:
+                popup_content += f"<b>Time Window:</b> {delivery['time_window']}<br>"
+            
+            # Add circle markers and other delivery visualizations
+            folium.Circle(
+                location=[lat, lon],
+                radius=50,
+                color=color,
+                fill=True,
+                fill_color=color,
+                fill_opacity=0.7,
+                tooltip=f"Stop {j+1}: {delivery['id']}"
+            ).add_to(m)
+            
+            # Add text label with stop number
+            folium.map.Marker(
+                [lat, lon],
+                icon=DivIcon(
+                    icon_size=(20, 20),
+                    icon_anchor=(10, 10),
+                    html=f'<div style="font-size: 12pt; color: #444444; font-weight: bold; text-align: center;">{j+1}</div>',
+                )
+            ).add_to(m)
+            
+            # Add regular marker with popup
+            folium.Marker(
+                [lat + 0.0003, lon],  # slight offset to not overlap with the circle
+                popup=folium.Popup(popup_content, max_width=300),
+                tooltip=f"Delivery {delivery['id']}",
+                icon=folium.Icon(color=color, icon='box', prefix='fa')
+            ).add_to(m)
+        
+        # Create road-based routes between each waypoint with progress tracking
+        for k in range(len(waypoints) - 1):
+            # Get start and end points of this segment
+            start_point = waypoints[k]
+            end_point = waypoints[k+1]
+            
+            # Create a key for this route segment
+            route_key = f"{vehicle_id}_{k}"
+            
+            # Update progress text
+            segment_desc = "depot" if k == 0 else f"stop {k}"
+            next_desc = f"stop {k+1}" if k < len(waypoints) - 2 else "depot"
+            
+            # Check if we have already calculated this route
+            if route_key in st.session_state.calculated_road_routes[optimization_key]:
+                # Use stored route
+                road_route = st.session_state.calculated_road_routes[optimization_key][route_key]
+                progress_text = f"Using stored route for Vehicle {vehicle_id}: {segment_desc} → {next_desc}"
+            else:
+                # Calculate and store new route
+                progress_text = f"Calculating route for Vehicle {vehicle_id}: {segment_desc} → {next_desc}"
+                with st.spinner(progress_text):
+                    # Get a road-like route between these points
+                    road_route = get_road_route(start_point, end_point)
+                    # Store for future use
+                    st.session_state.calculated_road_routes[optimization_key][route_key] = road_route
+            
+            # Add the route line (non-animated)
+            folium.PolyLine(
+                road_route,
+                color=color,
+                weight=4,
+                opacity=0.8,
+                tooltip=f"Route {vehicle_id}: {segment_desc} → {next_desc}"
+            ).add_to(m)
+            
+            # Add direction arrow
+            idx = int(len(road_route) * 0.7)
+            if idx < len(road_route) - 1:
+                p1 = road_route[idx]
+                p2 = road_route[idx + 1]
+                
+                # Calculate direction angle
+                dy = p2[0] - p1[0]
+                dx = p2[1] - p1[1]
+                angle = (90 - np.degrees(np.arctan2(dy, dx))) % 360
+                
+                # Add arrow marker
+                folium.RegularPolygonMarker(
+                    location=p1,
+                    number_of_sides=3,
+                    radius=8,
+                    rotation=angle,
+                    color=color,
+                    fill_color=color,
+                    fill_opacity=0.8
+                ).add_to(m)
+            
+            # Update progress after each segment
+            processed_segments += 1
+            progress_percentage = int((processed_segments / total_segments) * 100)
+            route_progress.progress(processed_segments / total_segments)
+            progress_container.text(f"Calculating routes: {progress_percentage}%")
+
+    # Add a message to show when using cached routes
+    if optimization_key in st.session_state.calculated_road_routes:
+        cached_count = len(st.session_state.calculated_road_routes[optimization_key])
+        if cached_count > 0 and cached_count >= processed_segments:
+            st.info(f"✅ Using {cached_count} previously calculated routes. No recalculation needed.")
+    
+    # Clear progress display when done
+    progress_container.empty()
+    route_progress.empty()
+    st.success("All routes calculated successfully!")
+    
+    # Display the map
+    folium_static(m, width=800, height=600)
+    
+    # -----------------------------------------------------
+    # Unified Schedule Calendar Section
+    # -----------------------------------------------------
+    st.subheader("Schedule Calendar View")
+    st.write("This calendar shows both delivery schedules and vehicle assignments. On-time deliveries are shown in green, late deliveries in red.")
+
+    # Process data for calendar view
+    if routes:
+        # First, collect all assigned deliveries and their details
+        calendar_data = []
+        
+        # Track which deliveries were actually included in routes
+        assigned_delivery_ids = set()
+        
+        # Step 1: Process all assigned deliveries first
+        for vehicle_id, route in routes.items():
+            for delivery in route:
+                assigned_delivery_ids.add(delivery['id'])
+                # Get vehicle info
+                vehicle_info = vehicle_data[vehicle_data['vehicle_id'] == vehicle_id].iloc[0]
+                vehicle_type = vehicle_info.get('vehicle_type', 'Standard')
+                driver_name = vehicle_info.get('driver_name', 'Unknown')
+                
+                # Extract delivery data
+                delivery_id = delivery['id']
+                customer_name = delivery.get('customer_name', 'Unknown')
+                priority = delivery.get('priority', 'Medium')
+                time_window = delivery.get('time_window', '09:00-17:00')
+                weight = delivery.get('weight_kg', 0)
+                
+                # Extract start and end times from time_window
+                start_time_str, end_time_str = time_window.split('-')
+                
+                # Get delivery date from original data
+                delivery_row = delivery_data[delivery_data['delivery_id'] == delivery_id]
+                delivery_date = delivery_row['delivery_date'].iloc[0] if not delivery_row.empty and 'delivery_date' in delivery_row else datetime.now().date()
+                
+                # Create start and end datetime for the delivery
+                try:
+                    # Convert to pandas datetime
+                    if isinstance(delivery_date, pd.Timestamp):
+                        date_str = delivery_date.strftime('%Y-%m-%d')
+                    elif isinstance(delivery_date, str):
+                        date_str = pd.to_datetime(delivery_date).strftime('%Y-%m-%d')
+                    else:
+                        date_str = delivery_date.strftime('%Y-%m-%d')
+                    
+                    start_datetime = pd.to_datetime(f"{date_str} {start_time_str}")
+                    end_datetime = pd.to_datetime(f"{date_str} {end_time_str}")
+                    
+                    # Check if this is on time (based on the estimated arrival from the route)
+                    estimated_arrival_mins = delivery.get('estimated_arrival', 0)
+                    
+                    # Convert time_window to minutes for comparison
+                    start_mins = int(start_time_str.split(':')[0]) * 60 + int(start_time_str.split(':')[1])
+                    end_mins = int(end_time_str.split(':')[0]) * 60 + int(end_time_str.split(':')[1])
+                    
+                    # Determine if delivery is on time
+                    on_time = start_mins <= estimated_arrival_mins <= end_mins
+                    
+                    # Set color based on on-time status and assignment
+                    if on_time:
+                        # Green for on-time
+                        color = 'on_time'
+                    else:
+                        # Red for not on-time
+                        color = 'late'
+
+                    calendar_data.append({
+                        'delivery_id': delivery_id,
+                        'customer_name': customer_name,
+                        'vehicle_id': vehicle_id,
+                        'driver_name': driver_name,
+                        'vehicle_type': vehicle_type,
+                        'priority': priority,
+                        'time_window': time_window,
+                        'estimated_arrival_mins': estimated_arrival_mins,
+                        'estimated_arrival_time': f"{estimated_arrival_mins//60:02d}:{estimated_arrival_mins%60:02d}",
+                        'weight_kg': weight,
+                        'Start': start_datetime,
+                        'Finish': end_datetime,
+                        'Task': f"{delivery_id}: {customer_name}",
+                        'Vehicle Task': f"{vehicle_id}: {driver_name}",
+                        'on_time': on_time,
+                        'assigned': True,
+                        'color': color,
+                        'delivery_date': pd.to_datetime(date_str)
+                    })
+                except Exception as e:
+                    st.warning(f"Could not process time window for delivery {delivery_id}: {str(e)}")
+        
+        # Step 2: Now add unassigned deliveries
+        for _, row in delivery_data.iterrows():
+            delivery_id = row['delivery_id']
+            
+            # Skip if already assigned
+            if delivery_id in assigned_delivery_ids:
+                continue
+                
+            # Extract data for unassigned delivery
+            customer_name = row.get('customer_name', 'Unknown')
+            priority = row.get('priority', 'Medium')
+            time_window = row.get('time_window', '09:00-17:00')
+            weight = row.get('weight_kg', 0)
+            
+            # Extract start and end times from time_window
+            start_time_str, end_time_str = time_window.split('-')
+            
+            # Get delivery date
+            if 'delivery_date' in row:
+                delivery_date = row['delivery_date']
+            else:
+                delivery_date = datetime.now().date()
+            
+            # Create start and end datetime
+            try:
+                # Convert to pandas datetime
+                if isinstance(delivery_date, pd.Timestamp):
+                    date_str = delivery_date.strftime('%Y-%m-%d')
+                elif isinstance(delivery_date, str):
+                    date_str = pd.to_datetime(delivery_date).strftime('%Y-%m-%d')
+                else:
+                    date_str = delivery_date.strftime('%Y-%m-%d')
+                
+                start_datetime = pd.to_datetime(f"{date_str} {start_time_str}")
+                end_datetime = pd.to_datetime(f"{date_str} {end_time_str}")
+                
+                # For unassigned deliveries set color to 'unassigned'
+                calendar_data.append({
+                    'delivery_id': delivery_id,
+                    'customer_name': customer_name,
+                    'vehicle_id': 'Unassigned',
+                    'driver_name': 'N/A',
+                    'vehicle_type': 'N/A',
+                    'priority': priority,
+                    'time_window': time_window,
+                    'estimated_arrival_mins': 0,
+                    'estimated_arrival_time': 'N/A',
+                    'weight_kg': weight,
+                    'Start': start_datetime,
+                    'Finish': end_datetime,
+                    'Task': f"{delivery_id}: {customer_name} (UNASSIGNED)",
+                    'Vehicle Task': 'Unassigned',
+                    'on_time': False,
+                    'assigned': False,
+                    'color': 'unassigned',  # Color for unassigned
+                    'delivery_date': pd.to_datetime(date_str)
+                })
+            except Exception as e:
+                st.warning(f"Could not process time window for unassigned delivery {delivery_id}: {str(e)}")
+        
+        if calendar_data:
+            # Convert to DataFrame
+            cal_df = pd.DataFrame(calendar_data)
+            
+            # Create color mapping for on-time status
+            cal_df['Color'] = cal_df['on_time'].map({True: 'rgb(0, 200, 0)', False: 'rgb(255, 0, 0)'})
+            
+            # Get all available dates 
+            all_dates = sorted(cal_df['delivery_date'].dt.date.unique())
+            
+            # Format dates for display in the dropdown
+            date_options = {date.strftime('%b %d, %Y'): date for date in all_dates}
+            
+            # Initialize calendar display dates if not already set or if dates have changed
+            available_date_keys = list(date_options.keys())
+            
+            # Default to all dates
+            if st.session_state.calendar_display_dates is None or not all(date in available_date_keys for date in st.session_state.calendar_display_dates):
+                st.session_state.calendar_display_dates = available_date_keys
+            
+            # Add multiselect for date filtering with session state
+            selected_date_strings = st.multiselect(
+                "Select dates to display",
+                options=available_date_keys,
+                default=st.session_state.calendar_display_dates,
+                key="calendar_date_selector"
+            )
+            
+            # Update the session state
+            st.session_state.calendar_display_dates = selected_date_strings
+            
+            # Convert selected strings back to date objects
+            selected_dates = [date_options[date_str] for date_str in selected_date_strings]
+            
+            if not selected_dates:
+                st.info("Please select at least one date to view the delivery schedule.")
+            else:
+                # Filter calendar data to only include selected dates
+                filtered_cal_df = cal_df[cal_df['delivery_date'].dt.date.isin(selected_dates)]
+                
+                # Create tabs only for the selected dates
+                date_tabs = st.tabs([date.strftime('%b %d, %Y') for date in selected_dates])
+                
+                for i, (date, tab) in enumerate(zip(selected_dates, date_tabs)):
+                    with tab:
+                        # Filter data for this date
+                        day_data = filtered_cal_df[filtered_cal_df['delivery_date'].dt.date == date]
+                        
+                        if len(day_data) > 0:
+                            # FIRST SECTION: DELIVERY SCHEDULE VIEW
+                            st.write("#### Delivery Schedule")
+                            
+                            # Create figure for delivery view
+                            fig = px.timeline(
+                                day_data, 
+                                x_start="Start", 
+                                x_end="Finish", 
+                                y="Task",
+                                color="color",  # Use our color column
+                                color_discrete_map={
+                                    "on_time": "green", 
+                                    "late": "orange",
+                                    "unassigned": "red"  # Unassigned deliveries also red
+                                },
+                                hover_data=["customer_name", "vehicle_id", "driver_name", "priority", "time_window", 
+                                           "estimated_arrival_time", "weight_kg", "assigned"]
+                            )
+                            
+                            # Fix the pattern application code
+                            for i, row in day_data.iterrows():
+                                # Only add diagonal pattern to assigned deliveries
+                                if row['assigned']:
+                                    for trace in fig.data:
+                                        # Find which trace corresponds to this row's color group
+                                        color_value = row['color']
+                                        
+                                        # Look for matching trace
+                                        if trace.name == color_value and any(y == row['Task'] for y in trace.y):
+                                            # Add pattern only to assigned bars
+                                            if 'marker' not in trace:
+                                                trace.marker = dict()
+                                            if 'pattern' not in trace.marker:
+                                                trace.marker.pattern = dict(
+                                                    shape="\\",  # Diagonal lines
+                                                    size=4,
+                                                    solidity=0.5,
+                                                    fgcolor="black"
+                                                )
+                            
+                            # Add status labels to the bars
+                            for idx, row in day_data.iterrows():
+                                status_text = "✓ On-time" if row['on_time'] and row['assigned'] else "⚠ Late" if row['assigned'] else "Not assigned"
+                                position = (row['Start'] + (row['Finish'] - row['Start'])/2)
+                                
+                                # Only add labels to assigned deliveries
+                                if row['assigned']:
+                                    fig.add_annotation(
+                                        x=position,
+                                        y=row['Task'],
+                                        text=status_text,
+                                        showarrow=False,
+                                        font=dict(color="black", size=10),
+                                        xanchor="center"
+                                    )
+                            
+                            # Update layout
+                            fig.update_layout(
+                                title=f"Deliveries by Customer - {date.strftime('%b %d, %Y')}",
+                                xaxis_title="Time of Day",
+                                yaxis_title="Delivery",
+                                height=max(300, 50 * len(day_data)),
+                                yaxis={'categoryorder':'category ascending'},
+                                showlegend=False  # Hide the legend as we have custom annotations
+                            )
+                            
+                            # Display figure
+                            st.plotly_chart(fig, use_container_width=True)
+                            
+                            # Show summary metrics for delivery view
+                            col1, col2, col3, col4 = st.columns(4)
+                            with col1:
+                                st.metric("Total Deliveries", len(day_data))
+                            with col2:
+                                st.metric("On-Time Deliveries", len(day_data[day_data['on_time']]))
+                            with col3:
+                                st.metric("Late Deliveries", len(day_data[~day_data['on_time']]))
+                            with col4:
+                                if 'weight_kg' in day_data.columns:
+                                    st.metric("Total Weight", f"{day_data['weight_kg'].sum():.2f} kg")
+                            
+                            # Add breakdown of deliveries by priority
+                            if 'priority' in day_data.columns:
+                                st.write("##### Deliveries by Priority")
+                                priority_counts = day_data['priority'].value_counts()
+                                priority_cols = st.columns(min(4, len(priority_counts)))
+                                
+                                for j, (priority, count) in enumerate(priority_counts.items()):
+                                    col_idx = j % len(priority_cols)
+                                    with priority_cols[col_idx]:
+                                        st.metric(priority, count)
+                            
+                            # SECOND SECTION: VEHICLE SCHEDULE VIEW
+                            st.write("#### Vehicle Schedule")
+                            
+                            # Create figure grouped by vehicle
+                            fig_vehicle = px.timeline(
+                                day_data, 
+                                x_start="Start", 
+                                x_end="Finish", 
+                                y="Vehicle Task",
+                                color="on_time",
+                                color_discrete_map={True: "green", False: "red"},
+                                hover_data=["delivery_id", "customer_name", "priority", "time_window", 
+                                           "estimated_arrival_time", "weight_kg"]
+                            )
+                            
+                            # Add labels for each delivery to the bars
+                            for idx, row in day_data.iterrows():
+                                fig_vehicle.add_annotation(
+                                    x=(row['Start'] + (row['Finish'] - row['Start'])/2),
+                                    y=row['Vehicle Task'],
+                                    text=f"#{row['delivery_id']}",
+                                    showarrow=False,
+                                    font=dict(size=10, color="black")
+                                )
+                            
+                            # Update layout
+                            fig_vehicle.update_layout(
+                                title=f"Vehicle Assignment Schedule - {date.strftime('%b %d, %Y')}",
+                                xaxis_title="Time of Day",
+                                yaxis_title="Vehicle",
+                                height=max(300, 70 * day_data['Vehicle Task'].nunique()),
+                                yaxis={'categoryorder':'category ascending'}
+                            )
+                            
+                            # Display figure for vehicle view
+                            st.plotly_chart(fig_vehicle, use_container_width=True)
+                            
+                            # Show vehicle utilization summary
+                            st.write("##### Vehicle Utilization")
+                            
+                            # Calculate vehicle utilization metrics
+                            vehicle_metrics = []
+                            for vehicle_id in day_data['vehicle_id'].unique():
+                                vehicle_deliveries = day_data[day_data['vehicle_id'] == vehicle_id]
+                                
+                                # Calculate total delivery time for this vehicle
+                                total_mins = sum((row['Finish'] - row['Start']).total_seconds() / 60 for _, row in vehicle_deliveries.iterrows())
+                                
+                                # Count on-time deliveries
+                                on_time_count = len(vehicle_deliveries[vehicle_deliveries['on_time'] == True])
+                                
+                                # Get the driver name
+                                driver_name = vehicle_deliveries['driver_name'].iloc[0] if not vehicle_deliveries.empty else "Unknown"
+                                
+                                vehicle_metrics.append({
+                                    'vehicle_id': vehicle_id,
+                                    'driver_name': driver_name,
+                                    'deliveries': len(vehicle_deliveries),
+                                    'delivery_time_mins': total_mins,
+                                    'on_time_deliveries': on_time_count,
+                                    'on_time_percentage': (on_time_count / len(vehicle_deliveries)) * 100 if len(vehicle_deliveries) > 0 else 0
+                                })
+                            
+                            # Display metrics in a nice format
+                            metrics_df = pd.DataFrame(vehicle_metrics)
+                            
+                            # Show as a table
+                            st.dataframe(metrics_df.style.format({
+                                'delivery_time_mins': '{:.0f}',
+                                'on_time_percentage': '{:.1f}%'
+                            }))
+                            
+                        else:
+                            st.info(f"No deliveries scheduled for {date.strftime('%b %d, %Y')}")
+        else:
+            st.info("No calendar data available. Please generate routes first.")
+
+def create_distance_matrix(locations):
+    """
+    Create a simple Euclidean distance matrix between locations
+    
+    In a real implementation, this would be replaced by actual road distances
+    
+    Parameters:
+        locations (list): List of location dictionaries with lat and lon
+        
+    Returns:
+        numpy.ndarray: Distance matrix
+    """
+    n = len(locations)
+    matrix = np.zeros((n, n))
+    for i in range(n):
+        for j in range(n):
+            if i == j:
+                continue
+            
+            # Approximate distance in km (very rough)
+            lat1, lon1 = locations[i]['latitude'], locations[i]['longitude']
+            lat2, lon2 = locations[j]['latitude'], locations[j]['longitude']
+            
+            # Simple Euclidean distance (for demo purposes)
+            # In reality, we'd use actual road distances
+            dist = ((lat1 - lat2) ** 2 + (lon1 - lon2) ** 2) ** 0.5 * 111
+            matrix[i, j] = dist
+    
+    return matrix
+
+def get_road_route(start_point, end_point):
+    """
+    Get a route that follows actual roads between two points using OpenStreetMap's routing service.
+    
+    Args:
+        start_point: (lat, lon) tuple of start location
+        end_point: (lat, lon) tuple of end location
+        
+    Returns:
+        list: List of (lat, lon) points representing the actual road route
+    """
+    try:
+        # OSRM expects coordinates in lon,lat format
+        start_lat, start_lon = start_point
+        end_lat, end_lon = end_point
+        
+        # Build the API URL for OSRM (OpenStreetMap Routing Machine)
+        url = f"http://router.project-osrm.org/route/v1/driving/{start_lon},{start_lat};{end_lon},{end_lat}"
+        params = {
+            "overview": "full",
+            "geometries": "geojson",
+            "steps": "true"
+        }
+        
+        # Replace direct text output with spinner
+        with st.spinner(f"Getting route from ({start_lat:.4f}, {start_lon:.4f}) to ({end_lat:.4f}, {end_lon:.4f})..."):
+            response = requests.get(url, params=params, timeout=5)
+            
+            if response.status_code == 200:
+                data = response.json()
+                
+                # Check if a route was found
+                if data['code'] == 'Ok' and len(data['routes']) > 0:
+                    # Extract the geometry (list of coordinates) from the response
+                    geometry = data['routes'][0]['geometry']['coordinates']
+                    
+                    # OSRM returns points as [lon, lat], but we need [lat, lon]
+                    route_points = [(lon, lat) for lat, lon in geometry]
+                    return route_points
+        
+        # If we get here, something went wrong with the API call
+        st.warning(f"Could not get road route: {response.status_code} - {response.text if response.status_code != 200 else 'No routes found'}")
+        
+    except Exception as e:
+        st.warning(f"Error getting road route: {str(e)}")
+    
+    # Fallback to our approximation method if the API call fails
+    with st.spinner("Generating approximate route..."):
+        # Create a more sophisticated approximation with higher density of points
+        start_lat, start_lon = start_point
+        end_lat, end_lon = end_point
+        
+        # Calculate the direct distance
+        direct_dist = ((start_lat - end_lat)**2 + (start_lon - end_lon)**2)**0.5
+        
+        # Generate more points for longer distances
+        num_points = max(10, int(direct_dist * 10000))  # Scale based on distance
+        
+        # Create a path with small random deviations to look like a road
+        route_points = []
+        
+        # Starting point
+        route_points.append((start_lat, start_lon))
+        
+        # Calculate major waypoints - like going through major roads
+        # Find a midpoint that's slightly off the direct line
+        mid_lat = (start_lat + end_lat) / 2
+        mid_lon = (start_lon + end_lon) / 2
+        
+        # Add some perpendicular deviation to simulate taking streets
+        # Get perpendicular direction
+        dx = end_lat - start_lat
+        dy = end_lon - start_lon
+        
+        # Perpendicular direction
+        perpendicular_x = -dy
+        perpendicular_y = dx
+        
+        # Normalize and scale
+        magnitude = (perpendicular_x**2 + perpendicular_y**2)**0.5
+        if magnitude > 0:
+            perpendicular_x /= magnitude
+            perpendicular_y /= magnitude
+        
+        # Scale the perpendicular offset based on distance
+        offset_scale = direct_dist * 0.2  # 20% of direct distance
+        
+        # Apply offset to midpoint
+        mid_lat += perpendicular_x * offset_scale * random.choice([-1, 1])
+        mid_lon += perpendicular_y * offset_scale * random.choice([-1, 1])
+        
+        # Generate a smooth path from start to midpoint
+        for i in range(1, num_points // 2):
+            t = i / (num_points // 2)
+            # Quadratic Bezier curve parameters
+            u = 1 - t
+            lat = u**2 * start_lat + 2 * u * t * mid_lat + t**2 * mid_lat
+            lon = u**2 * start_lon + 2 * u * t * mid_lon + t**2 * mid_lon
+            
+            # Add small random noise to make it look like following streets
+            noise_scale = 0.0002 * direct_dist
+            lat += random.uniform(-noise_scale, noise_scale)
+            lon += random.uniform(-noise_scale, noise_scale)
+            
+            route_points.append((lat, lon))
+        
+        # Generate a smooth path from midpoint to end
+        for i in range(num_points // 2, num_points):
+            t = (i - num_points // 2) / (num_points // 2)
+            # Quadratic Bezier curve parameters
+            u = 1 - t
+            lat = u**2 * mid_lat + 2 * u * t * mid_lat + t**2 * end_lat
+            lon = u**2 * mid_lon + 2 * u * t * mid_lon + t**2 * end_lon
+            
+            # Add small random noise to make it look like following streets
+            noise_scale = 0.0002 * direct_dist
+            lat += random.uniform(-noise_scale, noise_scale)
+            lon += random.uniform(-noise_scale, noise_scale)
+            
+            route_points.append((lat, lon))
+        
+        # Ending point
+        route_points.append((end_lat, end_lon))
+    
+    return route_points
+
+# Add this condition to make the function importable
+if __name__ == "__main__":
+    st.set_page_config(
+        page_title="Route Optimizer - Delivery Route Optimization",
+        page_icon="🛣️",
+        layout="wide"
+    )
+    optimize_page()

src/utils/__init__.py

@@ -0,0 +1 @@
+# This file is intentionally left blank.

src/utils/generate_all_data.py

@@ -0,0 +1,89 @@
+import os
+import sys
+from pathlib import Path
+
+# Add the project root directory to the Python path
+sys.path.append(str(Path(__file__).resolve().parent.parent.parent))
+
+def create_data_directory():
+    """
+    Ensure data directories exist for all generated files.
+    
+    This function creates the necessary directory structure to store
+    delivery data, vehicle data, and travel time matrices.
+    
+    Returns:
+    --------
+    tuple of (str, str, str)
+        Paths to time matrix directory, vehicle data directory, and delivery data directory    
+    """
+    vehicle_data_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), 'data', 'vehicle-data')
+    os.makedirs(vehicle_data_dir, exist_ok=True)
+
+    delivery_data_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), 'data', 'delivery-data')
+    os.makedirs(delivery_data_dir, exist_ok=True)
+
+    time_matrix_data_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), 'data', 'time-matrix')
+    os.makedirs(time_matrix_data_dir, exist_ok=True)
+    return time_matrix_data_dir, vehicle_data_dir, delivery_data_dir
+
+def main():
+    """
+    Run all data generation scripts for the delivery route optimization project.
+    
+    This function orchestrates the creation of all synthetic datasets needed for
+    the route optimization problem, including delivery data, vehicle data, and
+    travel time/distance matrices.
+    
+    Generated Files:
+    --------------
+    1. Delivery Data:
+       - Contains information about delivery locations, time windows, packages, etc.
+       - Used to define the delivery stops in the routing problem.
+       
+    2. Vehicle Data:
+       - Contains information about the delivery fleet, capacity, depots, etc.
+       - Used to define the available resources for delivery routes.
+       
+    3. Travel Matrices:
+       - Contains distance and time information between all locations.
+       - Used by the optimization algorithm to calculate route costs.
+       
+    Usage:
+    ------
+    These generated datasets form the foundation of the delivery route optimization
+    application. Together they define:
+    - Where deliveries need to be made (delivery data)
+    - What resources are available for deliveries (vehicle data)
+    - How long it takes to travel between locations (travel matrices)
+    
+    The route optimization algorithm uses these inputs to determine the most
+    efficient assignment of deliveries to vehicles and the optimal sequence of
+    stops for each vehicle.    
+    """
+    print("Starting data generation process...")
+    
+    time_matrix_data_dir, vehicle_data_dir, delivery_data_dir = create_data_directory()
+    print(f"Time Matrix Data will be saved to: {time_matrix_data_dir}")
+    print(f"Delivery Data will be saved to: {delivery_data_dir}")
+    print(f"Vehicle Data will be saved to: {vehicle_data_dir}")
+
+    # Import and run delivery data generation
+    print("\n1. Generating delivery data...")
+    from src.utils.generate_delivery_data import generate_delivery_data
+    delivery_data = generate_delivery_data(50, use_geocoding=True)
+    
+    # Import and run vehicle data generation
+    print("\n2. Generating vehicle data...")
+    from src.utils.generate_vehicle_data import generate_vehicle_data
+    vehicle_data = generate_vehicle_data(10)
+    
+    # Import and run travel matrix generation
+    print("\n3. Generating travel matrices...")
+    from src.utils.generate_travel_matrix import generate_travel_matrix
+    generate_travel_matrix()
+    
+    print("\nAll data generation complete! Files saved to data directory.")
+
+if __name__ == "__main__":
+    main()

src/utils/generate_delivery_data.py

@@ -0,0 +1,241 @@
+import pandas as pd
+import numpy as np
+import random
+from datetime import datetime, timedelta
+import os
+import time
+import requests
+from geopy.geocoders import Nominatim
+
+# Set random seed for reproducibility
+np.random.seed(42)
+
+def generate_delivery_data(n_deliveries=50, use_geocoding=False):
+    """
+    Generate synthetic delivery data with realistic Singapore addresses
+    """
+    # Define real Singapore neighborhoods and their actual streets
+    # Format: [neighborhood_name, [list_of_real_streets], postal_code_prefix]
+    sg_neighborhoods = [
+        ['Ang Mo Kio', ['Ang Mo Kio Avenue 1', 'Ang Mo Kio Avenue 3', 'Ang Mo Kio Avenue 4', 'Ang Mo Kio Avenue 10'], '56'],
+        ['Bedok', ['Bedok North Avenue 1', 'Bedok North Road', 'Bedok Reservoir Road', 'New Upper Changi Road'], '46'],
+        ['Bishan', ['Bishan Street 11', 'Bishan Street 12', 'Bishan Street 13', 'Bishan Street 22'], '57'],
+        ['Bukit Merah', ['Jalan Bukit Merah', 'Henderson Road', 'Tiong Bahru Road', 'Redhill Close'], '15'],
+        ['Bukit Batok', ['Bukit Batok East Avenue 6', 'Bukit Batok West Avenue 8', 'Bukit Batok Street 21'], '65'],
+        ['Clementi', ['Clementi Avenue 1', 'Clementi Avenue 4', 'Clementi Road', 'Commonwealth Avenue West'], '12'],
+        ['Geylang', ['Geylang East Avenue 1', 'Geylang Road', 'Guillemard Road', 'Sims Avenue'], '38'],
+        ['Hougang', ['Hougang Avenue 1', 'Hougang Avenue 7', 'Hougang Street 91', 'Upper Serangoon Road'], '53'],
+        ['Jurong East', ['Jurong East Street 13', 'Jurong East Avenue 1', 'Jurong Gateway Road'], '60'],
+        ['Jurong West', ['Jurong West Street 41', 'Jurong West Street 52', 'Jurong West Street 93'], '64'],
+        ['Kallang', ['Kallang Avenue', 'Geylang Bahru', 'Boon Keng Road', 'Upper Boon Keng Road'], '33'],
+        ['Punggol', ['Punggol Central', 'Punggol Field', 'Punggol Road', 'Punggol Way'], '82'],
+        ['Queenstown', ['Commonwealth Avenue', 'Commonwealth Drive', 'Mei Chin Road', 'Stirling Road'], '14'],
+        ['Sengkang', ['Sengkang East Way', 'Sengkang West Way', 'Compassvale Road', 'Fernvale Road'], '54'],
+        ['Serangoon', ['Serangoon Avenue 2', 'Serangoon Avenue 3', 'Serangoon North Avenue 1'], '55'],
+        ['Tampines', ['Tampines Street 11', 'Tampines Street 21', 'Tampines Avenue 1', 'Tampines Avenue 4'], '52'],
+        ['Toa Payoh', ['Toa Payoh Lorong 1', 'Toa Payoh Lorong 2', 'Toa Payoh Lorong 4', 'Toa Payoh Central'], '31'],
+        ['Woodlands', ['Woodlands Avenue 1', 'Woodlands Drive 16', 'Woodlands Drive 72', 'Woodlands Circle'], '73'],
+        ['Yishun', ['Yishun Avenue 1', 'Yishun Avenue 4', 'Yishun Ring Road', 'Yishun Street 22'], '76']
+    ]
+    
+    # Bounding boxes for neighborhoods (for fallback coordinates)
+    # Format: [name, min_lat, max_lat, min_lon, max_lon]
+    neighborhood_bounds = {
+        'Ang Mo Kio': [1.360000, 1.380000, 103.830000, 103.860000],
+        'Bedok': [1.320000, 1.335000, 103.920000, 103.950000],
+        'Bishan': [1.345000, 1.360000, 103.830000, 103.855000],
+        'Bukit Merah': [1.270000, 1.290000, 103.800000, 103.830000],
+        'Bukit Batok': [1.340000, 1.360000, 103.740000, 103.770000],
+        'Clementi': [1.310000, 1.325000, 103.750000, 103.780000],
+        'Geylang': [1.310000, 1.325000, 103.880000, 103.900000],
+        'Hougang': [1.370000, 1.385000, 103.880000, 103.900000],
+        'Jurong East': [1.330000, 1.345000, 103.730000, 103.750000],
+        'Jurong West': [1.340000, 1.360000, 103.690000, 103.720000],
+        'Kallang': [1.300000, 1.320000, 103.850000, 103.880000],
+        'Punggol': [1.390000, 1.410000, 103.900000, 103.920000],
+        'Queenstown': [1.290000, 1.310000, 103.780000, 103.805000],
+        'Sengkang': [1.380000, 1.395000, 103.870000, 103.900000],
+        'Serangoon': [1.345000, 1.360000, 103.865000, 103.885000],
+        'Tampines': [1.345000, 1.365000, 103.930000, 103.960000],
+        'Toa Payoh': [1.326000, 1.341000, 103.840000, 103.865000],
+        'Woodlands': [1.430000, 1.450000, 103.770000, 103.800000],
+        'Yishun': [1.410000, 1.430000, 103.820000, 103.850000]
+    }
+    
+    # Generate delivery IDs
+    delivery_ids = [f'DEL{str(i).zfill(4)}' for i in range(1, n_deliveries + 1)]
+    
+    # Generate customer names (fictional)
+    first_names = ['Tan', 'Lim', 'Lee', 'Ng', 'Wong', 'Chan', 'Goh', 'Ong', 'Teo', 'Koh', 
+                   'Chua', 'Loh', 'Yeo', 'Sim', 'Ho', 'Ang', 'Tay', 'Yap', 'Leong', 'Foo']
+    last_names = ['Wei', 'Ming', 'Hui', 'Ling', 'Yong', 'Jun', 'Hong', 'Xin', 'Yi', 'Jie',
+                  'Cheng', 'Kai', 'Zhi', 'Tian', 'Yu', 'En', 'Yang', 'Hao', 'Chong', 'Zheng']
+    customer_names = [f"{random.choice(first_names)} {random.choice(last_names)}" for _ in range(n_deliveries)]
+    
+    addresses = []
+    postal_codes = []
+    latitudes = []
+    longitudes = []
+    neighborhood_names = []
+    
+    # Initialize geocoder if using geocoding
+    if use_geocoding:
+        geolocator = Nominatim(user_agent="delivery_app")
+    
+    # Generate realistic addresses
+    for i in range(n_deliveries):
+        # Randomly select a neighborhood
+        neighborhood_data = random.choice(sg_neighborhoods)
+        neighborhood = neighborhood_data[0]
+        streets = neighborhood_data[1]
+        postal_prefix = neighborhood_data[2]
+        
+        # Randomly select a street in that neighborhood
+        street = random.choice(streets)
+        
+        # Generate block number (realistic for HDB)
+        block = random.randint(100, 600)
+        
+        # Generate unit number
+        unit_floor = random.randint(2, 20)
+        unit_number = random.randint(1, 150)
+        
+        # Generate postal code (with realistic prefix)
+        postal_suffix = str(random.randint(0, 999)).zfill(3)
+        postal_code = postal_prefix + postal_suffix
+        
+        # Create two formats of address - one for display, one for geocoding
+        display_address = f"Block {block}, #{unit_floor:02d}-{unit_number:03d}, {street}, Singapore {postal_code}"
+        geocode_address = f"{block} {street}, Singapore {postal_code}"  # Simpler format for geocoding
+        
+        # Default coordinates from neighborhood bounding box (fallback)
+        bounds = neighborhood_bounds[neighborhood]
+        default_lat = round(random.uniform(bounds[0], bounds[1]), 6)
+        default_lon = round(random.uniform(bounds[2], bounds[3]), 6)
+        
+        # Use geocoding API if requested
+        if use_geocoding:
+            try:
+                location = geolocator.geocode(geocode_address)
+                
+                if location:
+                    lat = location.latitude
+                    lon = location.longitude
+                    print(f"✓ Successfully geocoded: {geocode_address} → ({lat}, {lon})")
+                else:
+                    # First fallback: try with just street and postal code
+                    simpler_address = f"{street}, Singapore {postal_code}"
+                    location = geolocator.geocode(simpler_address)
+                    
+                    if location:
+                        lat = location.latitude
+                        lon = location.longitude
+                        print(f"✓ Fallback geocoded: {simpler_address} → ({lat}, {lon})")
+                    else:
+                        # Second fallback: just use the neighborhood center
+                        lat = default_lat
+                        lon = default_lon
+                        print(f"✗ Could not geocode: {geocode_address}, using neighborhood coordinates")
+                
+                # Add delay to avoid being rate limited
+                time.sleep(1)
+                
+            except Exception as e:
+                print(f"✗ Geocoding error for {geocode_address}: {str(e)}")
+                lat = default_lat
+                lon = default_lon
+        else:
+            # Without geocoding, use the default coordinates
+            lat = default_lat
+            lon = default_lon
+            
+        addresses.append(display_address)
+        postal_codes.append(postal_code)
+        latitudes.append(lat)
+        longitudes.append(lon)
+        neighborhood_names.append(neighborhood)
+    
+    # Generate delivery dates (within the next 7 days)
+    base_date = datetime.now().date()
+    delivery_dates = [base_date + timedelta(days=random.randint(1, 7)) for _ in range(n_deliveries)]
+    
+    # Generate time windows (between 9 AM and 5 PM)
+    time_windows = []
+    for _ in range(n_deliveries):
+        start_hour = random.randint(9, 16)
+        window_length = random.choice([1, 2, 3])  # 1, 2, or 3 hour windows
+        end_hour = min(start_hour + window_length, 18)
+        
+        start_time = f"{start_hour:02d}:00"
+        end_time = f"{end_hour:02d}:00"
+        time_windows.append(f"{start_time}-{end_time}")
+    
+    # Generate package details
+    weights = np.random.uniform(0.5, 20.0, n_deliveries)  # in kg
+    volumes = np.random.uniform(0.01, 0.5, n_deliveries)  # in m³
+    
+    # Priority levels
+    priorities = np.random.choice(['High', 'Medium', 'Low'], n_deliveries, 
+                                 p=[0.2, 0.5, 0.3])  # 20% High, 50% Medium, 30% Low
+    
+    # Required vehicle type
+    vehicle_types = np.random.choice(['Standard', 'Large', 'Refrigerated'], n_deliveries,
+                                   p=[0.7, 0.2, 0.1])
+    
+    # Status
+    statuses = np.random.choice(['Pending', 'Assigned', 'In Transit', 'Delivered'], n_deliveries,
+                              p=[0.6, 0.2, 0.15, 0.05])
+    
+    # Additional notes
+    notes = []
+    special_instructions = [
+        'Call customer before delivery', 
+        'Fragile items', 
+        'Leave at door',
+        'Signature required',
+        'No delivery on weekends',
+        None
+    ]
+    
+    for _ in range(n_deliveries):
+        if random.random() < 0.7:  # 70% chance of having a note
+            notes.append(random.choice(special_instructions))
+        else:
+            notes.append(None)
+    
+    # Create DataFrame
+    df = pd.DataFrame({
+        'delivery_id': delivery_ids,
+        'customer_name': customer_names,
+        'address': addresses,
+        'postal_code': postal_codes,
+        'neighborhood': neighborhood_names,
+        'latitude': latitudes,
+        'longitude': longitudes,
+        'delivery_date': delivery_dates,
+        'time_window': time_windows,
+        'weight_kg': weights.round(2),
+        'volume_m3': volumes.round(3),
+        'priority': priorities,
+        'vehicle_type': vehicle_types,
+        'status': statuses,
+        'special_instructions': notes
+    })
+    
+    # Ensure the directory exists
+    data_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), 'data', 'delivery-data')
+    os.makedirs(data_dir, exist_ok=True)
+    
+    # Save to CSV
+    output_path = os.path.join(data_dir, 'delivery_data.csv')
+    df.to_csv(output_path, index=False)
+    print(f"Delivery data generated and saved to {output_path}")
+    return df
+
+if __name__ == "__main__":
+    # Set to True if you want to use real geocoding (slower but more accurate)
+    USE_GEOCODING = True
+    delivery_data = generate_delivery_data(50, use_geocoding=USE_GEOCODING)
+    print("Sample of delivery data:")
+    print(delivery_data.head())
+

src/utils/generate_travel_matrix.py

@@ -0,0 +1,327 @@
+import pandas as pd
+import numpy as np
+import os
+import time
+import requests
+from math import radians, sin, cos, sqrt, atan2
+import random
+
+def haversine_distance(lat1, lon1, lat2, lon2):
+    """
+    Calculate the Haversine distance between two points in kilometers.
+    The Haversine distance is the great-circle distance between two points on a sphere.
+    
+    Parameters:
+    -----------
+    lat1, lon1 : float
+        Coordinates of the first point in decimal degrees
+    lat2, lon2 : float
+        Coordinates of the second point in decimal degrees
+        
+    Returns:
+    --------
+    float
+        Distance between the two points in kilometers
+    """
+    # Convert decimal degrees to radians
+    lat1, lon1, lat2, lon2 = map(radians, [lat1, lon1, lat2, lon2])
+    
+    # Haversine formula
+    dlon = lon2 - lon1
+    dlat = lat2 - lat1
+    a = sin(dlat/2)**2 + cos(lat1) * cos(lat2) * sin(dlon/2)**2
+    c = 2 * atan2(sqrt(a), sqrt(1-a))
+    distance = 6371 * c  # Radius of Earth in kilometers
+    
+    return distance
+
+def get_road_distance_with_retry(origin, destination, max_retries=3, initial_backoff=1):
+    """
+    Get road distance between two points with retry logic
+    
+    Parameters:
+    -----------
+    origin : dict
+        Origin location with 'latitude' and 'longitude' keys
+    destination : dict
+        Destination location with 'latitude' and 'longitude' keys
+    max_retries : int
+        Maximum number of retry attempts
+    initial_backoff : int
+        Initial backoff time in seconds
+    
+    Returns:
+    --------
+    tuple of (float, float)
+        Distance in km and duration in minutes
+    """
+    # URLs for different public OSRM instances to distribute load
+    osrm_urls = [
+        "http://router.project-osrm.org",
+        "https://routing.openstreetmap.de",
+        # Add more public OSRM servers if available
+    ]
+    
+    retry_count = 0
+    backoff = initial_backoff
+    
+    while retry_count < max_retries:
+        try:
+            # Use a random OSRM server from the list to distribute load
+            base_url = random.choice(osrm_urls)
+            url = f"{base_url}/route/v1/driving/{origin['longitude']},{origin['latitude']};{destination['longitude']},{destination['latitude']}?overview=false"
+            
+            # Add a timeout to prevent hanging connections
+            response = requests.get(url, timeout=5)
+            data = response.json()
+            
+            if data.get('code') == 'Ok':
+                # Extract distance and duration
+                distance = data['routes'][0]['distance'] / 1000  # meters to km
+                duration = data['routes'][0]['duration'] / 60    # seconds to minutes
+                return round(distance, 2), round(duration, 2)
+            else:
+                print(f"API returned error: {data.get('message', 'Unknown error')}")
+        
+        except requests.exceptions.RequestException as e:
+            print(f"Request failed: {e}. Retry {retry_count+1}/{max_retries}")
+        
+        # Exponential backoff with jitter to prevent thundering herd
+        jitter = random.uniform(0, 0.5 * backoff)
+        sleep_time = backoff + jitter
+        time.sleep(sleep_time)
+        backoff *= 2  # Exponential backoff
+        retry_count += 1
+    
+    # Fallback to haversine after all retries failed
+    print(f"All retries failed for route from ({origin['latitude']},{origin['longitude']}) to ({destination['latitude']},{destination['longitude']}). Using haversine distance.")
+    distance = haversine_distance(
+        origin['latitude'], origin['longitude'],
+        destination['latitude'], destination['longitude']
+    )
+    distance = distance * 1.3  # Road factor
+    time_mins = (distance / 40) * 60  # 40 km/h
+    
+    return round(distance, 2), round(time_mins, 2)
+
+def get_road_distance(origins, destinations, use_osrm=True):
+    """
+    Calculate actual road distances and travel times between multiple origins and destinations
+    using the OSRM (Open Source Routing Machine) API.
+    
+    Parameters:
+    -----------
+    origins : list of dict
+        List of origin locations with 'latitude' and 'longitude' keys
+    destinations : list of dict
+        List of destination locations with 'latitude' and 'longitude' keys
+    use_osrm : bool, default=True
+        Whether to use OSRM API or fall back to haversine distance
+        
+    Returns:
+    --------
+    tuple of (numpy.ndarray, numpy.ndarray)
+        Arrays containing distances (in km) and durations (in minutes) between each origin-destination pair
+    """
+    n_origins = len(origins)
+    n_destinations = len(destinations)
+    distance_matrix = np.zeros((n_origins, n_destinations))
+    duration_matrix = np.zeros((n_origins, n_destinations))
+    
+    # If OSRM is not requested, fall back to haversine distance
+    if not use_osrm:
+        print("Using haversine distance as fallback.")
+        for i, origin in enumerate(origins):
+            for j, dest in enumerate(destinations):
+                distance = haversine_distance(
+                    origin['latitude'], origin['longitude'],
+                    dest['latitude'], dest['longitude']
+                )
+                # Adjust for road networks (roads are typically not straight lines)
+                distance = distance * 1.3  # Apply a factor to approximate road distance
+                time_mins = (distance / 40) * 60  # Assuming average speed of 40 km/h
+                
+                distance_matrix[i, j] = round(distance, 2)
+                duration_matrix[i, j] = round(time_mins, 2)
+        return distance_matrix, duration_matrix
+    
+    # Process in batches to prevent overwhelming the API
+    print(f"Processing {n_origins} origins and {n_destinations} destinations in batches...")
+    total_requests = n_origins * n_destinations
+    completed = 0
+    
+    try:
+        # Try OSRM's table service for small datasets first (more efficient)
+        if n_origins + n_destinations <= 50:
+            print("Trying OSRM table API for efficient matrix calculation...")
+            try:
+                # Code for table API would go here, but we'll skip for now as it's more complex
+                # and the batch approach is more reliable for handling errors
+                raise NotImplementedError("Table API not implemented, falling back to individual routes")
+            except Exception as e:
+                print(f"Table API failed: {e}. Using individual routes instead.")
+                # Continue with individual route requests below
+        
+        # Process with individual route requests
+        for i, origin in enumerate(origins):
+            for j, dest in enumerate(destinations):
+                # Skip if origin and destination are the same point
+                if i == j:
+                    distance_matrix[i, j] = 0
+                    duration_matrix[i, j] = 0
+                    completed += 1
+                    continue
+                
+                # Get distance with retry logic
+                distance, duration = get_road_distance_with_retry(origin, dest)
+                distance_matrix[i, j] = distance
+                duration_matrix[i, j] = duration
+                
+                # Show progress
+                completed += 1
+                if completed % 10 == 0:
+                    print(f"Progress: {completed}/{total_requests} routes calculated ({(completed/total_requests)*100:.1f}%)")
+                
+                # Add randomized delay to prevent overwhelming the API
+                time.sleep(random.uniform(0.1, 0.5))
+    
+    except KeyboardInterrupt:
+        print("\nOperation interrupted by user. Saving partial results...")
+    
+    return distance_matrix, duration_matrix
+
+def generate_travel_matrix(use_osrm=True):
+    """
+    Generate travel time and distance matrices between all locations in the delivery problem.
+    
+    Parameters:
+    -----------
+    use_osrm : bool, default=True
+        Whether to use OSRM API for real road distances instead of haversine
+        
+    Returns:
+    --------
+    tuple of (pd.DataFrame, pd.DataFrame, dict)
+        Distance matrix, base time matrix, and hourly time matrices
+    """
+    # Create data directories if they don't exist
+    data_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), 'data')
+    time_matrix_dir = os.path.join(data_dir, 'time-matrix')
+    delivery_data_dir = os.path.join(data_dir, 'delivery-data')    
+    vehicle_data_dir = os.path.join(data_dir, 'vehicle-data')
+    
+    # Ensure all directories exist
+    for directory in [time_matrix_dir, delivery_data_dir, vehicle_data_dir]:
+        os.makedirs(directory, exist_ok=True)
+     
+    # Read delivery and vehicle data
+    try:
+        delivery_data = pd.read_csv(os.path.join(delivery_data_dir, 'delivery_data.csv'))
+        vehicle_data = pd.read_csv(os.path.join(vehicle_data_dir, 'vehicle_data.csv'))
+    except FileNotFoundError:
+        print("Error: Please generate delivery and vehicle data first!")
+        return
+    
+    # Extract locations
+    delivery_locations = delivery_data[['delivery_id', 'latitude', 'longitude']].values
+    depot_locations = vehicle_data[['vehicle_id', 'depot_latitude', 'depot_longitude']].values
+    
+    # Average speed for time calculation (km/h)
+    avg_speed = vehicle_data['avg_speed_kmh'].mean()
+    
+    # Traffic factor matrix (to simulate traffic conditions at different times)
+    hours_in_day = 24
+    traffic_factors = np.ones((hours_in_day, 1))
+    
+    # Simulate morning rush hour (8-10 AM)
+    traffic_factors[8:10] = 1.5
+    
+    # Simulate evening rush hour (5-7 PM)
+    traffic_factors[17:19] = 1.8
+    
+    # Late night (less traffic)
+    traffic_factors[22:] = 0.8
+    traffic_factors[:5] = 0.7
+    
+    # Create a combined list of all locations (depots + delivery points)
+    all_locations = []
+    
+    # Add depot locations
+    for row in depot_locations:
+        all_locations.append({
+            'id': row[0],  # vehicle_id as location id
+            'type': 'depot',
+            'latitude': row[1],
+            'longitude': row[2]
+        })
+    
+    # Add delivery locations
+    for row in delivery_locations:
+        all_locations.append({
+            'id': row[0],  # delivery_id as location id
+            'type': 'delivery',
+            'latitude': row[1],
+            'longitude': row[2]
+        })
+    
+    print(f"Calculating distances between {len(all_locations)} locations...")
+    
+    # Save the locations file early so we have this data even if the process is interrupted
+    location_df = pd.DataFrame(all_locations)
+    location_df.to_csv(os.path.join(time_matrix_dir, 'locations.csv'), index=False)
+    
+    # Calculate distances and times using OSRM with improved error handling
+    if use_osrm:
+        print("Using OSRM API for road distances...")
+        distance_matrix, base_time_matrix = get_road_distance(all_locations, all_locations, use_osrm=True)
+    else:
+        print("Using haversine distance with road factor adjustment...")
+        distance_matrix, base_time_matrix = get_road_distance(all_locations, all_locations, use_osrm=False)
+    
+    # Create DataFrames for the matrices
+    location_ids = [loc['id'] for loc in all_locations]
+    
+    distance_df = pd.DataFrame(distance_matrix, index=location_ids, columns=location_ids)
+    time_df = pd.DataFrame(base_time_matrix, index=location_ids, columns=location_ids)
+    
+    # Save distance and base time matrices early in case later steps fail
+    distance_df.to_csv(os.path.join(time_matrix_dir, 'distance_matrix.csv'))
+    time_df.to_csv(os.path.join(time_matrix_dir, 'base_time_matrix.csv'))
+    print("Basic distance and time matrices saved successfully.")
+    
+    # Create time matrices for different hours of the day
+    hourly_time_matrices = {}
+    for hour in range(24):
+        traffic_factor = traffic_factors[hour][0]
+        hourly_time = base_time_matrix * traffic_factor
+        hourly_time_matrices[f"{hour:02d}:00"] = pd.DataFrame(hourly_time, index=location_ids, columns=location_ids)
+    
+    # Save a sample of time matrices (e.g., rush hour and normal time)
+    try:
+        hourly_time_matrices['08:00'].to_csv(os.path.join(time_matrix_dir, 'morning_rush_time_matrix.csv'))
+        hourly_time_matrices['18:00'].to_csv(os.path.join(time_matrix_dir, 'evening_rush_time_matrix.csv'))
+        hourly_time_matrices['12:00'].to_csv(os.path.join(time_matrix_dir, 'midday_time_matrix.csv'))
+        hourly_time_matrices['00:00'].to_csv(os.path.join(time_matrix_dir, 'night_time_matrix.csv'))
+        print("Time matrices for different hours saved successfully.")
+    except Exception as e:
+        print(f"Error saving hourly time matrices: {e}")
+        print("Continuing with basic matrices only.")
+    
+    print("Travel matrices generation complete.")
+    return distance_df, time_df, hourly_time_matrices
+
+if __name__ == "__main__":
+    # For development, allow falling back to haversine if needed
+    import argparse
+    
+    parser = argparse.ArgumentParser(description="Generate travel matrices for delivery route optimization")
+    parser.add_argument("--use-osrm", action="store_true", help="Use OSRM API for real road distances")
+    parser.add_argument("--use-haversine", action="store_true", help="Use haversine distance only (faster)")
+    
+    args = parser.parse_args()
+    
+    if args.use_haversine:
+        generate_travel_matrix(use_osrm=False)
+    else:
+        # Default to OSRM unless explicitly disabled
+        generate_travel_matrix(use_osrm=True) 

src/utils/generate_vehicle_data.py

@@ -0,0 +1,168 @@
+import pandas as pd
+import numpy as np
+import random
+from datetime import datetime, timedelta
+import os
+
+# Set random seed for reproducibility
+np.random.seed(43)
+
+def generate_vehicle_data(n_vehicles=10):
+    """
+    Generate synthetic vehicle data for a delivery fleet optimization problem.
+    
+    This function creates a realistic delivery fleet with various vehicle types,
+    capacities, and operational parameters to be used in route optimization.
+    
+    Parameters:
+    -----------
+    n_vehicles : int, default=10
+        Number of vehicles to generate in the fleet
+    
+    Returns:
+    --------
+    pd.DataFrame
+        DataFrame containing the generated vehicle data
+    """
+    
+    # Vehicle IDs
+    vehicle_ids = [f'VEH{str(i).zfill(3)}' for i in range(1, n_vehicles + 1)]
+    
+    # Vehicle types
+    vehicle_types = []
+    for _ in range(n_vehicles):
+        vehicle_type = random.choices(['Standard', 'Large', 'Refrigerated'], 
+                                     weights=[0.7, 0.2, 0.1])[0]
+        vehicle_types.append(vehicle_type)
+    
+    # Vehicle capacities based on type
+    max_weights = []
+    max_volumes = []
+    for v_type in vehicle_types:
+        if v_type == 'Standard':
+            max_weights.append(random.uniform(800, 1200))
+            max_volumes.append(random.uniform(8, 12))
+        elif v_type == 'Large':
+            max_weights.append(random.uniform(1500, 2500))
+            max_volumes.append(random.uniform(15, 25))
+        else:  # Refrigerated
+            max_weights.append(random.uniform(600, 1000))
+            max_volumes.append(random.uniform(6, 10))
+    
+    # Realistic depot/warehouse locations in Singapore industrial areas
+    # [name, latitude, longitude]
+    warehouse_locations = [
+        ["Tuas Logistics Hub", 1.3187, 103.6390],
+        ["Jurong Industrial Estate", 1.3233, 103.6994],
+        ["Loyang Industrial Park", 1.3602, 103.9761],
+        ["Changi Logistics Centre", 1.3497, 103.9742],
+        ["Keppel Distripark", 1.2706, 103.8219],
+        ["Pandan Logistics Hub", 1.3187, 103.7509],
+        ["Alexandra Distripark", 1.2744, 103.8012],
+        ["Kallang Way Industrial", 1.3315, 103.8731],
+        ["Defu Industrial Park", 1.3610, 103.8891],
+        ["Woodlands Industrial", 1.4428, 103.7875]
+    ]
+    
+    # Assign warehouses to vehicles (multiple vehicles can be from same warehouse)
+    # Either assign sequentially to ensure all warehouses are used at least once (if n_vehicles >= len(warehouse_locations)),
+    # or randomly select from the list
+    depot_names = []
+    depot_lats = []
+    depot_lons = []
+    
+    if n_vehicles <= len(warehouse_locations):
+        # Use first n_vehicles warehouses (one vehicle per warehouse)
+        selected_warehouses = warehouse_locations[:n_vehicles]
+    else:
+        # Ensure every warehouse is used at least once
+        selected_warehouses = warehouse_locations.copy()
+        # Then add random ones for remaining vehicles
+        remaining = n_vehicles - len(warehouse_locations)
+        selected_warehouses.extend([random.choice(warehouse_locations) for _ in range(remaining)])
+    
+    # Shuffle to avoid sequential assignment
+    random.shuffle(selected_warehouses)
+    
+    # Extract depot information
+    for warehouse in selected_warehouses:
+        depot_names.append(warehouse[0])
+        depot_lats.append(warehouse[1])
+        depot_lons.append(warehouse[2])
+    
+    # Add small variation for vehicles from the same warehouse (within warehouse compound)
+    # This makes each vehicle's position slightly different, simulating different loading bays
+    for i in range(len(depot_lats)):
+        # Much smaller variation - within warehouse compound (approximately 50-100m variation)
+        depot_lats[i] += random.uniform(-0.0005, 0.0005)
+        depot_lons[i] += random.uniform(-0.0005, 0.0005)
+    
+    # Driver names
+    first_names = ['Ahmad', 'Raj', 'Michael', 'Wei', 'Siti', 'Kumar', 'Chong', 'David', 'Suresh', 'Ali']
+    last_names = ['Tan', 'Singh', 'Lee', 'Wong', 'Kumar', 'Abdullah', 'Zhang', 'Lim', 'Raj', 'Teo']
+    driver_names = []
+    
+    for i in range(n_vehicles):
+        if i < len(first_names):
+            driver_names.append(f"{first_names[i]} {random.choice(last_names)}")
+        else:
+            driver_names.append(f"{random.choice(first_names)} {random.choice(last_names)}")
+    
+    # Vehicle availability
+    start_times = [f"{random.randint(7, 10):02d}:00" for _ in range(n_vehicles)]
+    end_times = [f"{random.randint(17, 21):02d}:00" for _ in range(n_vehicles)]
+    
+    # Max working hours
+    max_working_hours = [random.randint(8, 10) for _ in range(n_vehicles)]
+    
+    # Average speed (km/h)
+    avg_speeds = [random.uniform(30, 50) for _ in range(n_vehicles)]
+    
+    # Cost per km
+    cost_per_km = [random.uniform(0.5, 1.5) for _ in range(n_vehicles)]
+    
+    # Vehicle status
+    statuses = np.random.choice(['Available', 'In Service', 'Maintenance'], n_vehicles, p=[0.7, 0.2, 0.1])
+    
+    # License plates (Singapore format)
+    letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+    license_plates = []
+    for _ in range(n_vehicles):
+        letter_part = ''.join(random.choices(letters, k=3))
+        number_part = random.randint(1000, 9999)
+        license_plates.append(f"S{letter_part}{number_part}")
+    
+    # Create DataFrame
+    df = pd.DataFrame({
+        'vehicle_id': vehicle_ids,
+        'vehicle_type': vehicle_types,
+        'license_plate': license_plates,
+        'driver_name': driver_names,
+        'max_weight_kg': np.array(max_weights).round(2),
+        'max_volume_m3': np.array(max_volumes).round(2),
+        'depot_name': depot_names,
+        'depot_latitude': np.array(depot_lats).round(6),
+        'depot_longitude': np.array(depot_lons).round(6),
+        'start_time': start_times,
+        'end_time': end_times,
+        'max_working_hours': max_working_hours,
+        'avg_speed_kmh': np.array(avg_speeds).round(2),
+        'cost_per_km': np.array(cost_per_km).round(2),
+        'status': statuses
+    })
+    
+    # Ensure the directory exists
+    data_dir = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(__file__))), 'data', 'vehicle-data')
+    os.makedirs(data_dir, exist_ok=True)
+    
+    # Save to CSV
+    output_path = os.path.join(data_dir, 'vehicle_data.csv')
+    df.to_csv(output_path, index=False)
+    print(f"Vehicle data generated and saved to {output_path}")
+    return df
+
+if __name__ == "__main__":
+    # Generate vehicle data
+    vehicle_data = generate_vehicle_data(10)
+    print("Sample of vehicle data:")
+    print(vehicle_data.head())