bluebird-api 0.1.0__tar.gz

bluebird_api-0.1.0/.gitignore

@@ -0,0 +1,192 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.python-version
+
+# 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
+/docs/src/examples/**/*.ipynb
+/docs/src/examples/**/*.gif
+
+# 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
+
+# Vim temporary files
+*.swp
+*.swo
+
+# VSCode config
+.vscode/
+
+# emacs autosave
+*~
+
+# BluebirdATC files
+bluebird-dt/bluebird_dt/scenario_data/scenario_logs/*
+
+# MacOS files
+.DS_store

bluebird_api-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: bluebird-api
+Version: 0.1.0
+Summary: A REST API for the Project Bluebird Digital Twin
+Author: Project Bluebird
+License-Expression: AGPL-3.0-or-later
+Requires-Python: <3.15,>=3.10
+Requires-Dist: bluebird-dt
+Requires-Dist: fastapi<0.137,>=0.136.1
+Requires-Dist: lxml-html-clean>=0.4.4
+Requires-Dist: uvicorn<0.47,>=0.46.0
+Description-Content-Type: text/markdown
+
+## The REST API for BluebirdATC
+
+It is possible to run the BluebirdATC digital twin in a server process, such that the simulation will evolve at regular time intervals, and Agents and/or frontend visualization software can interact with it via HTTP requests.
+In particular, users can:
+* Query available scenario categories and scenarios.
+* Load a selected scenario.
+* Evolve the simulation by a specified time interval.
+* Obtain the current state of the `Environment`.
+* Submit `Actions` to individual aircraft.
+* Save logfiles with data on all steps of the simulation.
+
+In order to run the app, with all the correct dependencies for this feature, from the `BluebirdATC/bluebird-api` directory, run the command:
+
+```shell
+uv run uvicorn bluebird_api:app --port 8000
+```
+
+You should then be able to go to [http://localhost:8000](http://localhost:8000) in a web browser, and see the message "Hello, BluebirdATC!".
+
+To see the full list and description of API endpoints, with the application running, go to [http://localhost:8000/docs](http://localhost:8000/docs).
+
+## Frontend visualisation
+
+The app also serves the frontend visualization (more details on that can be found [here](../bluebird-hmi/README.md)), at the URL [http://localhost:8000/hmi](http://localhost:8000/hmi).

bluebird_api-0.1.0/README.md

@@ -0,0 +1,24 @@
+## The REST API for BluebirdATC
+
+It is possible to run the BluebirdATC digital twin in a server process, such that the simulation will evolve at regular time intervals, and Agents and/or frontend visualization software can interact with it via HTTP requests.
+In particular, users can:
+* Query available scenario categories and scenarios.
+* Load a selected scenario.
+* Evolve the simulation by a specified time interval.
+* Obtain the current state of the `Environment`.
+* Submit `Actions` to individual aircraft.
+* Save logfiles with data on all steps of the simulation.
+
+In order to run the app, with all the correct dependencies for this feature, from the `BluebirdATC/bluebird-api` directory, run the command:
+
+```shell
+uv run uvicorn bluebird_api:app --port 8000
+```
+
+You should then be able to go to [http://localhost:8000](http://localhost:8000) in a web browser, and see the message "Hello, BluebirdATC!".
+
+To see the full list and description of API endpoints, with the application running, go to [http://localhost:8000/docs](http://localhost:8000/docs).
+
+## Frontend visualisation
+
+The app also serves the frontend visualization (more details on that can be found [here](../bluebird-hmi/README.md)), at the URL [http://localhost:8000/hmi](http://localhost:8000/hmi).

bluebird_api-0.1.0/bluebird_api/__init__.py

@@ -0,0 +1,77 @@
+import logging
+import os
+import re
+from collections.abc import Awaitable, Callable
+from pathlib import Path
+
+from bluebird_dt import logger
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
+from fastapi.routing import APIRoute
+from fastapi.staticfiles import StaticFiles
+
+from .route_tags import tags_metadata
+from .routes import router
+
+bluebird_logger = logging.getLogger("bluebird_dt")
+bluebird_logger.setLevel(logging.DEBUG)
+stream_handler = logging.StreamHandler()
+stream_handler.setFormatter(logger.CustomFormatter())
+bluebird_logger.addHandler(stream_handler)
+
+app = FastAPI(
+    title="BluebirdATC: AI for air traffic control",
+    description="FastAPI interface to control the simulation framework BluebirdATC.",
+    license_info={
+        "name": "License",
+        "url": "https://github.com/project-bluebird/BluebirdATC/blob/dev/LICENSE",
+    },
+    openapi_tags=tags_metadata,
+    strict_content_type=False,
+)
+app.include_router(router)
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+app.add_middleware(GZipMiddleware, minimum_size=500)
+
+# serve the frontend
+repo_root = Path(__file__).resolve().parents[2]
+dist_path = repo_root / "bluebird-hmi" / "dist"
+
+if dist_path.is_dir():
+    app.mount("/hmi", StaticFiles(directory=str(dist_path), html=True), name="frontend")
+    app.mount("/hmi/assets", StaticFiles(directory=os.path.join(dist_path, "assets")), name="assets")
+
+
+# For webapp, requests will be prepended with "/api" - strip that out here
+@app.middleware("http")
+async def strip_api_prefix(request: Request, call_next: Callable[[Request], Awaitable[Response]]) -> Response:
+    path = request.url.path
+    if path.startswith("/api"):
+        newpath = re.sub("/api", "", path)
+        request.scope["path"] = newpath
+    return await call_next(request)
+
+
+def use_route_names_as_operation_ids(app: FastAPI) -> None:
+    """
+    Simplify operation IDs so that generated API clients have simpler function
+    names.
+
+    Must be called after all routes have been added.
+    """
+    for route in app.routes:
+        if isinstance(route, APIRoute):
+            route.operation_id = route.name
+
+
+use_route_names_as_operation_ids(app)
+
+# keep track of current simulation instance
+# app.state.current_runner = None

bluebird_api-0.1.0/bluebird_api/models.py

@@ -0,0 +1,39 @@
+import typing
+
+from bluebird_dt.utility.supported_actions import SUPPORTED_ACTIONS
+from pydantic import BaseModel, Field
+
+from bluebird_api.runnerabc import RunnerABC
+
+SUPPORTED_ACTIONS_LIST = [action for actions in SUPPORTED_ACTIONS.values() for action in actions]
+
+
+class RunnerStore:
+    current_runner: RunnerABC = None
+
+
+class ActionInput(BaseModel):
+    """An action to be sent to the simulator."""
+
+    agent: str = Field(
+        description="The agent performing the action.",
+        json_schema_extra={"example": "atc_1"},
+    )
+    callsign: str = Field(
+        description="The callsign of the flight being acted on.",
+        json_schema_extra={"example": "AIR123"},
+    )
+    kind: typing.Literal[tuple(SUPPORTED_ACTIONS_LIST)] = Field(
+        description="The kind of action to perform. Must be a string that is one of the supported actions.",
+        json_schema_extra={"example": "change_heading_to"},
+    )
+    value: typing.Any = Field(
+        description=(
+            "The value associated with the action. The type of this value depends on the action being performed."
+        ),
+        json_schema_extra={"example": 90},
+    )
+    sector: str = Field(
+        description="The sector that the action is being performed in.",
+        json_schema_extra={"example": "sector_1"},
+    )

bluebird_api-0.1.0/bluebird_api/route_tags.py

@@ -0,0 +1,23 @@
+# FastAPI metadata tags for use in Swagger autodocs.
+tags_metadata = [
+    {
+        "name": "Control",
+        "description": "High level control of BluebirdATC.",
+    },
+    {
+        "name": "Scenarios",
+        "description": "Routes to get information about scenarios.",
+    },
+    {
+        "name": "Evolve",
+        "description": "Routes to start, stop and evolve the simulation.",
+    },
+    {
+        "name": "State",
+        "description": "Routes to get the state of the simulation.",
+    },
+    {
+        "name": "Submit",
+        "description": "Routes to submit actions, plans and more to the simulation.",
+    },
+]

bluebird_api-0.1.0/bluebird_api/routers/__init__.py

@@ -0,0 +1,19 @@
+"""
+This module contains all the routers for the different features available in BluebirdATC. Note that, unlike in compiled
+programming languages where disabled features are not included in the machine code, not including certain routers just
+means that the endpoint is not available but the logic will continue to be available in BluebirdATC,
+and therefore logged.
+
+All the following routers are independent on the implementation of the storage of the runners and get this through the
+fastapi dependency. See the respective documentation in ../runnerabc.py.
+
+Note the endpoint for loading a run, that the HMI and most clients expect, is not included here as they are dependent on
+the implementation of the store, which is dependent on the use case. An example of this endpoint, and any other
+endpoints not included within the groups defined here are available in ../routes.py
+"""
+
+from .core import core_router
+
+__all__ = [
+    "core_router",
+]