Get Started#

Prerequisites#

System requirements: Verify that your system meets the minimum requirements.
Docker platform: Install Docker platform. For installation instructions, see Get Docker.
You are familiar with Docker commands and using the terminal. If you are new to Docker platform, see Docker Documentation for an introduction.

Quick Start with Setup Script#

Clone the Repository :

If you want to clone a specific release branch, replace main with the desired tag. To learn more on partial cloning, check the Repository Cloning guide.

git clone --filter=blob:none --sparse --branch main https://github.com/open-edge-platform/metro-ai-suite.git
cd metro-ai-suite
git sparse-checkout set smart-route-planning-agent
cd smart-route-planning-agent

Configure Smart Traffic Intersection Agent Node Endpoints :

In order to plan routes, Smart Route Planning Agent needs Smart Traffic Intersection Agents running on pre-defined nodes. See this to learn more.

Edit src/data/config.json to add the IP addresses and ports of the edge nodes where Smart Traffic Intersection Agents are running.

Example Configuration

{
    "api_endpoint": "/api/v1/traffic/current/ws?images=false",
    "api_hosts": [
        {
            "host": "ws://<node-1-ip>:<port>"
        },
        {
            "host": "ws://<node-2-ip>:<port>"
        },
        {
            "host": "ws://<node-3-ip>:<port>"
        }
    ]
}

Set the required environment variables :

export REASONING_MODEL_NAME=<model-name>    # e.g. OpenVINO/Qwen3.6-35B-A3B-int4-ov, OpenVINO/Qwen3.5-9B-int8-ov, OpenVINO/Qwen2.5-14B-Instruct-int4-ov
export TAG=latest   # Make sure TAG is set to latest to pull the latest image.

Run the Smart Route Planning Agent along with all dependencies :
```
source setup.sh --run
```

Note: When deployed for the first time, the AI model is downloaded and converted to required format. This can take several minutes depending on your network. This model is later cached in a Docker volume, so that restarts or next deployments with same models are fast. Set HF_TOKEN environment variable, as well, if the model repository is gated.

Stop the application :#

To stop and remove the containers for the application and its dependencies :

source setup.sh --stop

To restart the application along with all the dependencies :

source setup.sh --restart

To stop application along with cleaning up all the associated volumes and images: (Caution: This will remove all downloaded AI models for the application. Next run will re-download these models.)

source setup.sh --clean

Validated AI Models#

The following models were measured on Intel® Xeon® 5th Gen CPU:

Model	Precision	Size	Suitability
`OpenVINO/Qwen3.5-9B-int8-ov`	INT8	9GB	Dense INT8 model, suitable for basic reasoning on moderate compute environments.
`OpenVINO/Qwen3.6-35B-A3B-int4-ov`	INT4	20GB	MoE Sparse Model, Requires less compute for the performance delivered by models with similar number of parameters.
`OpenVINO/Qwen2.5-14B-Instruct-int4-ov`	INT4	15GB	Dense, considerably large number of parameters. Might require tweaking `OVMS_CACHE_SIZE` and `REASONING_TIMEOUT_SEC`.

IMPORTANT: On slower hardware prefer a smaller model or consider increasing the value of REASONING_TIMEOUT_SEC or OVMS_CACHE_SIZE. See Environment Variables Guide

Note: Before adopting a model that is not listed above, please validate it for the map updates in the UI without the fallback notice. If the OVMS container restarts repeatedly, the model is most likely not compatible.

Fallback behaviour#

The agent automatically falls back to rule based planning for that update, whenever:

the model server is unreachable, still loading, or times out,
the model could not make a decision
the model hallucinates (For example, names a route that does not exist or has no live traffic data.)

Manual Setup for Advanced Users#

For advanced users who need more control over the configuration, you can set up the stack manually using Docker Compose tool.

Manual Environment Configuration#

If you prefer to configure environment variables manually instead of using the setup script, see the Environment Variables Guide for details.

Build from Source and Deploy#

See Build from Source for instructions on building and running with the Docker Compose tool.

Helm Deployment#

See Deploy with Helm for a simple Kubernetes deployment flow.

Multi-Node Stack for Smart Route Planning Agent#

The Smart Route Planning Agent works in a multi-node setup with one central Smart Route Planning Agent and multiple Smart Traffic Intersection Agent edge nodes.

Architecture Overview#

Architecture Overview

Multi-Node Deployment Prerequisites#

Deploy the Smart Traffic Intersection Agent on each edge node.
Ensure network connectivity between the central node and edge nodes.
Note the IP address and port of each Smart Traffic Intersection Agent.
Update the api_hosts field in the src/data/config.json file with all the edge node’s IP address and port. See this for example configuration.

Note

We can add api_hosts for even just one instance, however minimum three instances of Smart Traffic Intersection Agent is recommended for proper route planning in the application.

Deploy the Route Planning Agent#

After configuring the edge node endpoints, deploy the Smart Route Planning Agent on the central node:

source setup.sh --run

The Route Planning Agent will query all configured Smart Traffic Intersection Agents to gather live traffic data for route optimization.