agi-app-uav-relay-queue 0.1.0__py3-none-any.whl

agi_app_uav_relay_queue/__init__.py

@@ -0,0 +1,33 @@
+"""Installed AGILAB app project provider for uav_relay_queue_project."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+APP_SLUG = 'uav_relay_queue'
+PROJECT_NAME = 'uav_relay_queue_project'
+PACKAGE_NAME = 'agi-app-uav-relay-queue'
+
+
+def package_root() -> Path:
+    return Path(__file__).resolve().parent
+
+
+def project_root() -> Path:
+    packaged_root = package_root() / "project" / PROJECT_NAME
+    if packaged_root.exists():
+        return packaged_root
+    source_root = Path(__file__).resolve().parents[4] / "apps" / "builtin" / PROJECT_NAME
+    return source_root if source_root.exists() else packaged_root
+
+
+def metadata() -> dict[str, str]:
+    return {
+        "slug": APP_SLUG,
+        "project": PROJECT_NAME,
+        "package": PACKAGE_NAME,
+        "project_root": str(project_root()),
+    }
+
+
+__all__ = ["APP_SLUG", "PACKAGE_NAME", "PROJECT_NAME", "metadata", "package_root", "project_root"]

agi_app_uav_relay_queue/project/uav_relay_queue_project/README.md

@@ -0,0 +1,64 @@
+# UAV Relay Queue Project
+
+`uav_relay_queue_project` is the AGILAB install id for this built-in lightweight UAV
+relay queue example.
+
+The project demonstrates a compact routing-and-queueing simulation:
+- one UAV source
+- one ground sink
+- two relay choices with different queue and delay trade-offs
+- exported telemetry that can be inspected in AGILAB analysis pages
+
+Origin note:
+
+- this built-in example is conceptually inspired by the SimPy buffer-based
+  queueing pattern described in
+  [`UavNetSim`](https://github.com/Zihao-Felix-Zhou/UavNetSim)
+  (MIT-licensed)
+- it does not vendor or claim to adapt UavNetSim source code directly
+
+## What it is good for
+
+- a self-contained AGILAB demo app
+- quick queue-aware routing experiments
+- understanding how relay congestion changes packet delivery, delay, and queue depth
+
+## What is not implemented in the public version
+
+This public built-in example is intentionally lightweight. It does **not** implement:
+- a full external UAV network simulator or emulator backend
+- detailed radio, PHY, or MAC behavior
+- large topology families or operational-scale routing stacks
+- production-grade routing control traffic, interference, or energy models
+- a complete research benchmark for UAV networking
+
+The goal is to keep the public example easy to run while still making queue buildup,
+relay choice, delay, and drops visible inside AGILAB.
+
+## Main outputs
+
+Each run exports:
+- queue time series
+- packet events
+- relay routing summary
+- node positions
+- `pipeline/topology.gml`
+- `pipeline/allocations_steps.csv`
+- trajectory CSVs for `view_maps_network`
+
+## Typical flow
+
+1. Select `uav_relay_queue_project` in `PROJECT`.
+2. Run it from `ORCHESTRATE`.
+3. Inspect queue artifacts in `view_relay_resilience`.
+4. Inspect topology and trajectories in `view_maps_network`.
+
+## What this teases in AGILAB
+
+The same framework can support richer network studies than this public demo shows.
+With dedicated apps and pages, AGILAB can be used to:
+- run larger scenario sweeps through `ORCHESTRATE` and `WORKFLOW`
+- attach custom analysis pages to domain-specific artifacts
+- compare routing variants across repeatable experiment runs
+- distribute experiments across workers instead of keeping everything local
+- evolve a lightweight demo into a more advanced simulator-backed workflow

agi_app_uav_relay_queue/project/uav_relay_queue_project/lab_stages.toml

@@ -0,0 +1,4 @@
+uav_relay_queue = [
+  { D = "Seed the UAV relay queue scenario", Q = "Load or seed the compact UAV relay queue scenario and expose two relay paths toward one sink.", M = "", C = "APP = 'uav_relay_queue_project'\nscenario = 'uav_queue_hotspot'\nrouting_policy = 'shortest_path'", R = "runpy" },
+  { D = "Run the relay queue policy", Q = "Execute the chosen relay policy and export packet, queue, and trajectory artifacts for analysis.", M = "", C = "APP = 'uav_relay_queue_project'\nrouting_policy = 'queue_aware'\ndata_in = 'uav_relay_queue/scenarios'\ndata_out = 'uav_relay_queue/results'", R = "runpy" },
+]

agi_app_uav_relay_queue/project/uav_relay_queue_project/notebook_export.toml

@@ -0,0 +1,26 @@
+[notebook_export]
+
+[[notebook_export.related_pages]]
+module = "view_relay_resilience"
+label = "UAV Relay Queue Analysis"
+description = "Inspect queue depth, packet delivery, relay routing summary, and node positions for the relay-queue demo."
+artifacts = [
+  "*_summary_metrics.json",
+  "*_queue_timeseries.csv",
+  "*_packet_events.csv",
+  "*_node_positions.csv",
+  "*_routing_summary.csv",
+]
+launch_note = "Open this first for the dedicated relay queue analysis view over the exported run artifacts."
+
+[[notebook_export.related_pages]]
+module = "view_maps_network"
+label = "Maps Network"
+description = "Reuse the same relay run as a topology, allocation, and trajectory map."
+artifacts = [
+  "pipeline/topology.gml",
+  "pipeline/allocations_steps.csv",
+  "*_trajectory_summary.json",
+  "*_trajectory*.csv",
+]
+launch_note = "Use this when you want the generic topology and trajectory exploration path for the same run."

agi_app_uav_relay_queue/project/uav_relay_queue_project/pipeline_view.dot

@@ -0,0 +1,13 @@
+digraph uav_relay_queue_pipeline {
+  rankdir=LR;
+  graph [fontname="Helvetica", fontsize=10];
+  node [shape=box, style="rounded,filled", fillcolor="#F5F7FA", color="#2F4B7C", fontname="Helvetica", fontsize=10];
+  edge [color="#4C78A8", arrowsize=0.8];
+
+  scenario [label="Scenario JSON\nsource + relays + sink"];
+  simulate [label="UAV relay queue simulation\nshortest_path | queue_aware"];
+  analysis [label="AGILAB ANALYSIS\nview_relay_resilience\nview_maps_network"];
+
+  scenario -> simulate;
+  simulate -> analysis;
+}

agi_app_uav_relay_queue/project/uav_relay_queue_project/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "uav_relay_queue_project"
+version = "0.1.0"
+description = "Built-in AGILAB lightweight UAV relay queue example"
+requires-python = ">=3.13"
+dependencies = ["agi-env>=2026.05.13.post3,<2027.0", "agi-node>=2026.05.13.post3,<2027.0", "agi-cluster>=2026.05.13.post3,<2027.0", "networkx", "pandas>=2.3.0", "pydantic", "simpy>=4.1,<5", "streamlit>=1.56.0"]
+
+[tool.setuptools.package-data]
+uav_relay_queue = ["sample_data/*.json"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

agi_app_uav_relay_queue/project/uav_relay_queue_project/service_templates/train_then_serve_policy_run.json

@@ -0,0 +1,65 @@
+{
+  "schema": "agilab.example.train_then_serve.v1",
+  "training_run": {
+    "app": "sb3_trainer_project",
+    "trainer": "uav_relay_queue_ppo",
+    "run_id": "trainer_uav_relay_queue_ppo_preview",
+    "model_artifact": "sb3_trainer/pipeline/trainer_uav_relay_queue_ppo/uav_queue_model.zip",
+    "metrics": {
+      "delivery_ratio": 0.96,
+      "p95_latency_ms": 61.0,
+      "reward_mean": 42.5
+    }
+  },
+  "service": {
+    "name": "uav_relay_policy_service",
+    "version": "2026.05.preview",
+    "health_thresholds": {
+      "latency_budget_ms": 80.0,
+      "allow_idle": false,
+      "max_unhealthy": 0,
+      "max_restart_rate": 0.25
+    },
+    "input_schema": {
+      "source_queue_depth": "float 0..1",
+      "candidate_relays": "list of relay features"
+    },
+    "output_schema": {
+      "selected_relay": "relay id",
+      "action": "route_via_relay",
+      "confidence": "float 0..1"
+    }
+  },
+  "prediction_request": {
+    "source_queue_depth": 0.82,
+    "candidate_relays": [
+      {
+        "id": "relay_alpha",
+        "latency_ms": 72.0,
+        "queue_depth": 0.74,
+        "capacity_mbps": 7.5,
+        "risk": 0.22
+      },
+      {
+        "id": "relay_beta",
+        "latency_ms": 55.0,
+        "queue_depth": 0.41,
+        "capacity_mbps": 9.4,
+        "risk": 0.11
+      },
+      {
+        "id": "relay_gamma",
+        "latency_ms": 63.0,
+        "queue_depth": 0.35,
+        "capacity_mbps": 8.1,
+        "risk": 0.08
+      }
+    ]
+  },
+  "policy_scoring": {
+    "capacity_mbps": 0.42,
+    "latency_ms": -0.18,
+    "queue_depth": -0.28,
+    "risk": -0.12
+  }
+}

agi_app_uav_relay_queue/project/uav_relay_queue_project/src/app_args_form.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+from typing import Any
+
+import streamlit as st
+from pydantic import ValidationError
+
+_HERE = Path(__file__).resolve().parent
+if str(_HERE) not in sys.path:
+    sys.path.insert(0, str(_HERE))
+
+from uav_relay_queue import UavRelayQueueArgs, dump_args, load_args
+
+
+PAGE_ID = "uav_relay_queue_project:app_args_form"
+
+
+def _k(name: str) -> str:
+    return f"{PAGE_ID}:{name}"
+
+
+def _get_env():
+    env = st.session_state.get("env") or st.session_state.get("_env")
+    if env is None:
+        st.error("AGILab environment is not initialised yet. Return to the main page and try again.")
+        st.stop()
+    return env
+
+
+def _load_current_args(settings_path: Path) -> UavRelayQueueArgs:
+    try:
+        return load_args(settings_path)
+    except Exception as exc:
+        st.warning(f"Unable to load UAV relay queue args from `{settings_path}`: {exc}")
+        return UavRelayQueueArgs()
+
+
+env = _get_env()
+settings_path = Path(env.app_settings_file)
+current_args = _load_current_args(settings_path)
+current_payload = current_args.model_dump(mode="json")
+
+try:
+    share_root = env.share_root_path()
+except Exception:
+    share_root = None
+
+artifact_root = Path(getattr(env, "AGILAB_EXPORT_ABS", Path.home() / "export")) / env.target / "queue_analysis"
+
+st.caption(
+    "This built-in app runs a lightweight UAV relay queue simulation with explicit "
+    f"packet and queue telemetry. Analysis artifacts are exported to `{artifact_root}`."
+)
+if share_root:
+    st.caption(f"Current shared root: `{share_root}`")
+
+defaults = {
+    "data_in": str(current_payload.get("data_in", "") or ""),
+    "data_out": str(current_payload.get("data_out", "") or ""),
+    "files": str(current_payload.get("files", "*.json") or "*.json"),
+    "nfile": int(current_payload.get("nfile", 1) or 1),
+    "routing_policy": str(current_payload.get("routing_policy", "shortest_path") or "shortest_path"),
+    "sim_time_s": float(current_payload.get("sim_time_s", 30.0) or 30.0),
+    "sampling_interval_s": float(current_payload.get("sampling_interval_s", 0.5) or 0.5),
+    "source_rate_pps": float(current_payload.get("source_rate_pps", 14.0) or 14.0),
+    "queue_weight": float(current_payload.get("queue_weight", 2.5) or 2.5),
+    "random_seed": int(current_payload.get("random_seed", 2026) or 2026),
+    "reset_target": bool(current_payload.get("reset_target", False)),
+}
+for key, value in defaults.items():
+    st.session_state.setdefault(_k(key), value)
+
+c1, c2, c3, c4 = st.columns([2, 2, 1.2, 1.2])
+with c1:
+    st.text_input("Scenario directory", key=_k("data_in"))
+with c2:
+    st.text_input("Results directory", key=_k("data_out"))
+with c3:
+    st.text_input("Files glob", key=_k("files"))
+with c4:
+    st.number_input("Number of files", key=_k("nfile"), min_value=1, step=1)
+
+c5, c6, c7 = st.columns([1.5, 1.2, 1.1])
+with c5:
+    st.selectbox("Routing policy", options=["shortest_path", "queue_aware"], key=_k("routing_policy"))
+with c6:
+    st.number_input("Sim time (s)", key=_k("sim_time_s"), min_value=2.0, max_value=600.0, step=1.0)
+with c7:
+    st.checkbox("Reset output", key=_k("reset_target"))
+
+c8, c9, c10, c11 = st.columns([1.1, 1.1, 1.1, 1.1])
+with c8:
+    st.number_input("Sampling (s)", key=_k("sampling_interval_s"), min_value=0.1, max_value=10.0, step=0.1)
+with c9:
+    st.number_input("Source rate (pps)", key=_k("source_rate_pps"), min_value=0.1, max_value=500.0, step=0.5)
+with c10:
+    st.number_input("Queue weight", key=_k("queue_weight"), min_value=0.0, max_value=20.0, step=0.1)
+with c11:
+    st.number_input("Random seed", key=_k("random_seed"), min_value=0, step=1)
+
+candidate: dict[str, Any] = {
+    "files": (st.session_state.get(_k("files")) or "*.json").strip() or "*.json",
+    "nfile": st.session_state.get(_k("nfile"), 1),
+    "routing_policy": st.session_state.get(_k("routing_policy")) or "shortest_path",
+    "sim_time_s": st.session_state.get(_k("sim_time_s"), 30.0),
+    "sampling_interval_s": st.session_state.get(_k("sampling_interval_s"), 0.5),
+    "source_rate_pps": st.session_state.get(_k("source_rate_pps"), 14.0),
+    "queue_weight": st.session_state.get(_k("queue_weight"), 2.5),
+    "random_seed": st.session_state.get(_k("random_seed"), 2026),
+    "reset_target": bool(st.session_state.get(_k("reset_target"), False)),
+}
+
+data_in_raw = (st.session_state.get(_k("data_in")) or "").strip()
+data_out_raw = (st.session_state.get(_k("data_out")) or "").strip()
+if data_in_raw:
+    candidate["data_in"] = data_in_raw
+if data_out_raw:
+    candidate["data_out"] = data_out_raw
+
+try:
+    validated = UavRelayQueueArgs(**candidate)
+except ValidationError as exc:
+    st.error("Invalid UAV relay queue parameters:")
+    if hasattr(env, "humanize_validation_errors"):
+        for msg in env.humanize_validation_errors(exc):
+            st.markdown(msg)
+    else:
+        st.code(str(exc))
+else:
+    validated_payload = validated.model_dump(mode="json")
+    if validated_payload != current_payload:
+        dump_args(validated, settings_path)
+        app_settings = st.session_state.get("app_settings")
+        if not isinstance(app_settings, dict):
+            app_settings = {}
+        app_settings.setdefault("cluster", {})
+        app_settings["args"] = validated_payload
+        app_settings.setdefault("pages", {})
+        app_settings["pages"]["view_module"] = ["view_relay_resilience", "view_maps_network"]
+        st.session_state["app_settings"] = app_settings
+        st.session_state["is_args_from_ui"] = True
+        st.success(f"Saved to `{settings_path}`.")
+    else:
+        st.info("No changes to save.")
+
+    resolved_data_in = env.resolve_share_path(validated.data_in)
+    resolved_data_out = env.resolve_share_path(validated.data_out)
+    if not any(resolved_data_in.glob(validated.files)):
+        st.info("No matching scenario file exists yet. The bundled sample scenario will be seeded on first run.")
+    st.caption(
+        f"Resolved input: `{resolved_data_in}`  •  results: `{resolved_data_out}`  •  "
+        f"analysis artifacts: `{artifact_root}`"
+    )
+    st.caption(
+        "The default sample is tuned to create a queue hotspot on `relay_a` under "
+        "`shortest_path`, then improve when you switch to `queue_aware`."
+    )
+    st.caption(
+        "Each run also exports `pipeline/topology.gml`, `pipeline/allocations_steps.csv`, and "
+        "per-node trajectory CSVs so `view_maps_network` can reuse the same scenario."
+    )

agi_app_uav_relay_queue/project/uav_relay_queue_project/src/app_settings.toml

@@ -0,0 +1,54 @@
+[args]
+data_in = "uav_relay_queue/scenarios"
+data_out = "uav_relay_queue/results"
+files = "*.json"
+nfile = 1
+routing_policy = "shortest_path"
+sim_time_s = 30.0
+sampling_interval_s = 0.5
+source_rate_pps = 14.0
+queue_weight = 2.5
+random_seed = 2026
+reset_target = false
+
+[cluster]
+verbose = 1
+cython = false
+pool = false
+rapids = false
+cluster_enabled = false
+scheduler = "127.0.0.1:8786"
+workers_data_path = ""
+
+[cluster.workers]
+"127.0.0.1" = 2
+
+[cluster.service_health]
+allow_idle = false
+max_unhealthy = 0
+max_restart_rate = 0.25
+
+[connector_catalog]
+path = "connectors/data_connectors.toml"
+
+[connector_refs]
+scenario_sql = "uav_relay_queue_scenarios_sql"
+operator_events = "uav_relay_queue_ops_opensearch"
+artifact_store = "uav_relay_queue_artifact_store"
+
+[page_connector_refs.view_relay_resilience]
+relay_metrics = "uav_relay_queue_artifact_store"
+operator_events = "uav_relay_queue_ops_opensearch"
+
+[page_connector_refs.view_maps_network]
+network_evidence = "uav_relay_queue_ops_opensearch"
+
+[legacy_paths]
+data_in = "uav_relay_queue/scenarios"
+data_out = "uav_relay_queue/results"
+
+[pages]
+view_module = [
+    "view_relay_resilience",
+    "view_maps_network",
+]

agi_app_uav_relay_queue/project/uav_relay_queue_project/src/connectors/data_connectors.toml

@@ -0,0 +1,27 @@
+[[connectors]]
+id = "uav_relay_queue_scenarios_sql"
+kind = "sql"
+label = "UAV Relay Queue Scenarios SQL"
+description = "Read-only relay scenario and topology metadata source."
+uri = "postgresql://uav.example.invalid/relay_queue"
+driver = "postgresql"
+query_mode = "read_only"
+
+[[connectors]]
+id = "uav_relay_queue_ops_opensearch"
+kind = "opensearch"
+label = "UAV Relay Queue Operations OpenSearch"
+description = "Relay simulation run and operator evidence index."
+url = "https://opensearch.example.invalid"
+index = "agilab-uav-relay-queue-*"
+auth_ref = "env:OPENSEARCH_TOKEN"
+
+[[connectors]]
+id = "uav_relay_queue_artifact_store"
+kind = "object_storage"
+label = "UAV Relay Queue Artifact Store"
+description = "Object-storage prefix for relay simulation artifacts."
+provider = "s3"
+bucket = "agilab-artifacts"
+prefix = "uav_relay_queue/"
+auth_ref = "env:AWS_PROFILE"

agi_app_uav_relay_queue/project/uav_relay_queue_project/src/pre_prompt.json

@@ -0,0 +1 @@
+[]

agi_app_uav_relay_queue/project/uav_relay_queue_project/src/uav_relay_queue/__init__.py

@@ -0,0 +1,30 @@
+"""Application surface for the built-in UAV relay queue example."""
+
+from .app_args import (
+    UavRelayQueueArgs,
+    UavRelayQueueArgsTD,
+    UavQueueArgs,
+    UavQueueArgsTD,
+    dump_args,
+    ensure_defaults,
+    load_args,
+    merge_args,
+)
+from .reduction import UAV_RELAY_QUEUE_REDUCE_CONTRACT
+from .uav_relay_queue import UavRelayQueue, UavRelayQueueApp, UavQueue, UavQueueApp
+
+__all__ = [
+    "UAV_RELAY_QUEUE_REDUCE_CONTRACT",
+    "UavRelayQueue",
+    "UavRelayQueueApp",
+    "UavRelayQueueArgs",
+    "UavRelayQueueArgsTD",
+    "UavQueue",
+    "UavQueueApp",
+    "UavQueueArgs",
+    "UavQueueArgsTD",
+    "dump_args",
+    "ensure_defaults",
+    "load_args",
+    "merge_args",
+]

agi_app_uav_relay_queue/project/uav_relay_queue_project/src/uav_relay_queue/app_args.py

@@ -0,0 +1,94 @@
+"""Argument helpers for the built-in UAV relay queue example."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal, TypedDict
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from agi_env.app_args import dump_model_to_toml, load_model_from_toml, merge_model_data
+
+
+class UavRelayQueueArgs(BaseModel):
+    """Runtime parameters for the lightweight UAV relay queue demo."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    data_in: Path = Field(default_factory=lambda: Path("uav_relay_queue/scenarios"))
+    data_out: Path = Field(default_factory=lambda: Path("uav_relay_queue/results"))
+    files: str = "*.json"
+    nfile: int = Field(default=1, ge=1, le=50)
+    routing_policy: Literal["shortest_path", "queue_aware"] = "shortest_path"
+    sim_time_s: float = Field(default=30.0, gt=1.0, le=600.0)
+    sampling_interval_s: float = Field(default=0.5, gt=0.0, le=10.0)
+    source_rate_pps: float = Field(default=14.0, gt=0.0, le=500.0)
+    queue_weight: float = Field(default=2.5, ge=0.0, le=20.0)
+    random_seed: int = Field(default=2026, ge=0)
+    reset_target: bool = False
+
+    @model_validator(mode="after")
+    def _validate_consistency(self) -> "UavRelayQueueArgs":
+        self.files = self.files.strip() or "*.json"
+        if self.sampling_interval_s >= self.sim_time_s:
+            raise ValueError("sampling_interval_s must be smaller than sim_time_s")
+        return self
+
+
+class UavRelayQueueArgsTD(TypedDict, total=False):
+    data_in: str
+    data_out: str
+    files: str
+    nfile: int
+    routing_policy: str
+    sim_time_s: float
+    sampling_interval_s: float
+    source_rate_pps: float
+    queue_weight: float
+    random_seed: int
+    reset_target: bool
+
+
+ArgsModel = UavRelayQueueArgs
+ArgsOverrides = UavRelayQueueArgsTD
+UavQueueArgs = UavRelayQueueArgs
+UavQueueArgsTD = UavRelayQueueArgsTD
+
+
+def load_args(settings_path: str | Path, *, section: str = "args") -> UavRelayQueueArgs:
+    return load_model_from_toml(UavRelayQueueArgs, settings_path, section=section)
+
+
+def merge_args(
+    base: UavRelayQueueArgs,
+    overrides: UavRelayQueueArgsTD | None = None,
+) -> UavRelayQueueArgs:
+    return merge_model_data(base, overrides)
+
+
+def dump_args(
+    args: UavRelayQueueArgs,
+    settings_path: str | Path,
+    *,
+    section: str = "args",
+    create_missing: bool = True,
+) -> None:
+    dump_model_to_toml(args, settings_path, section=section, create_missing=create_missing)
+
+
+def ensure_defaults(args: UavRelayQueueArgs, **_: Any) -> UavRelayQueueArgs:
+    return args
+
+
+__all__ = [
+    "ArgsModel",
+    "ArgsOverrides",
+    "UavRelayQueueArgs",
+    "UavRelayQueueArgsTD",
+    "UavQueueArgs",
+    "UavQueueArgsTD",
+    "dump_args",
+    "ensure_defaults",
+    "load_args",
+    "merge_args",
+]