Flight Project
==============

Overview
--------
- End-to-end reference project that ingests aeronautical telemetry, cleans it
  with `Polars` and pushes curated artefacts back into the AGILab export
  directory.
- Demonstrates how to orchestrate file-based distributions, run inside the
  cluster pool and keep the Streamlit user interface responsive while the
  worker pipeline operates asynchronously.
- Bundles Streamlit lab material (``lab_steps.toml``) and prompt examples to help
  you reproduce the workflow showcased in AGILab live demos.

Manager (`flight.flight`)
-------------------------
- Wraps the runnable application. Converts user-supplied arguments into a
  validated `FlightArgs` model, normalises data URIs, and initialises cluster
  dispatch by seeding ``WorkDispatcher``.
- Provides ``from_toml`` / ``to_toml`` helpers so snippets on the Execute page can
  reload configuration and persist overrides.
- Handles managed-PC specifics (path remapping, data directory resets) and keeps
  the dataframe export folder clean between runs.

Args (`flight.flight_args`)
---------------------------
- Pydantic models that capture the full surface area of the project’s
  configuration, including dataset location, slicing parameters and cluster
  toggles.
- Ships conversion utilities for reading/writing ``app_settings.toml`` and merging
  overrides that are injected by the Execute page.

Worker (`flight_worker.flight_worker`)
--------------------------------------
- Extends ``PolarsWorker`` to preprocess raw telemetry, compute geodesic distances
  between samples, and partition files across the cluster.
- Contains Cython hooks (``flight_worker.pyx``) and pre/post-install scripts so
  you can see how compiled extensions are integrated into a distribution.
- Demonstrates Windows-friendly path handling and data staging for managed
  environments.

Assets & Tests
--------------
- ``app_test.py`` exercises the full install → distribute → run flow.
- ``test/_test_*`` modules focus on unit-level behaviour for manager, worker and
  orchestration glue.
- ``Modules`` and ``lab_steps.toml`` contain the Streamlit lab material used by
  the Experiment page.

API Reference
-------------

.. image:: diagrams/packages_flight.svg
   :width: 400
   :alt: flight package dependencies
   :align: center

.. automodule:: flight.flight
   :members:
   :undoc-members:
   :show-inheritance:

.. image:: diagrams/classes_flight.svg
   :width: 400
   :alt: flight class diagram
   :align: center

.. automodule:: flight.flight_args
   :members:
   :undoc-members:
   :show-inheritance:

.. image:: diagrams/classes_flight_args.svg
   :width: 400
   :alt: flight args class diagram
   :align: center

.. image:: diagrams/packages_flight_worker.svg
   :width: 400
   :alt: flight worker package diagram
   :align: center

.. automodule:: flight_worker.flight_worker
   :members:
   :undoc-members:
   :show-inheritance:

.. image:: diagrams/classes_flight_worker.svg
   :width: 400
   :alt: flight worker class diagram
   :align: center