Quick Start Guide

This guide will get you running your first control application in minutes using ai_nn_controller.

The framework supports any type of network node — optical, wireless, RAN, core network, and more.

Starting the Services

Start the infrastructure using Docker Compose:

docker compose up -d

This starts Redis, the registration service, the message broker, the six example optical network nodes, and the aic_server container, which runs three cooperating example applications by default: NetworkApp1, NetworkApp2, and ConflictMitigator (see Conflict Mitigation Example).

Verify services are running:

docker compose ps
curl http://localhost:8000/health

Accessing the API

The AIC Server provides a REST API and MCP endpoints:

Managing Applications

List All Applications

curl http://localhost:8000/apps

Response — the default aic_server container runs three apps out of the box:

{
  "apps": [
    {
      "name": "NetworkApp1",
      "state": "stopped",
      "aic_app_id": 1,
      "cell_ids": [3, 4, 5, 6, 7, 8],
      "control_loop_update_time": 2
    },
    {
      "name": "NetworkApp2",
      "state": "stopped",
      "aic_app_id": 2,
      "cell_ids": [3, 8],
      "control_loop_update_time": 2
    },
    {
      "name": "ConflictMitigator",
      "state": "stopped",
      "aic_app_id": 3,
      "cell_ids": [8],
      "control_loop_update_time": 2
    }
  ],
  "total": 3
}

NetworkApp1 and NetworkApp2 both periodically send SET_GAIN to node 8, which is why ConflictMitigator exists — it resolves the conflict by priority and re-queues only the winning command. NetworkApp1 also declares required_plugins = ["ConsolePlugin"]; see Developing Plugins. See Conflict Mitigation Example for the full pattern.

Start an Application

curl -X PUT http://localhost:8000/apps/NetworkApp1/state \
  -H "Content-Type: application/json" \
  -d '{"state": "running"}'

Get Application State

curl http://localhost:8000/apps/NetworkApp1/state

Get Measurements

curl http://localhost:8000/apps/NetworkApp1/measurements

Send a Manual Command

curl -X POST http://localhost:8000/apps/NetworkApp1/control \
  -H "Content-Type: application/json" \
  -d '{
    "node_id": 8,
    "command": "SET_GAIN",
    "payload": {"amp_type": "preamp", "target_gain": 15.0}
  }'

Creating Your First App

Create a new file my_app.py:

from ai_nn_controller.decorators.aic_app import aic_app
from ai_nn_controller.AicApp import AicApp
from ai_nn_controller.AicController import AicController

@aic_app(name="MyFirstApp")
class MyFirstApp(AicApp):
    """A simple app that monitors a single node."""

    aic_app_id = 100
    control_loop_update_time = 2

    # Subscribe to measurements from node 3
    read_measurements = {
        3: ["amp1_target_gain", "amp1_gain_tilt"]
    }

    # No control functions for now
    control_functions = {}

    # cell_ids and send_commands are auto-generated by @aic_app

    @classmethod
    def process(cls, measurements):
        """Called every control_loop_update_time seconds with new measurements."""
        if not measurements:
            print("[MyFirstApp] Waiting for measurements...")
            return

        latest = measurements.get(3, [{}])[-1]
        gain = latest.get("amp1_target_gain", "N/A")
        tilt = latest.get("amp1_gain_tilt", "N/A")

        print(f"[MyFirstApp] Node 3 — Gain: {gain}, Tilt: {tilt}")

if __name__ == "__main__":
    AicController(with_api=True, api_port=8000, verbose=True).run()

Run the app:

python my_app.py --verbose

Your app will:

  1. Register with the registration service

  2. Connect to the message broker

  3. Start receiving measurements from node 3

  4. Print measurements every 2 seconds

  5. Expose REST API at http://localhost:8000

Using MCP Tools

ai_nn_controller auto-generates MCP tools for AI agent integration:

List Available Tools

curl http://localhost:8000/mcp/tools

Call a Tool

curl -X POST http://localhost:8000/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyFirstApp_get_state",
    "arguments": {}
  }'

Viewing Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f aic_server

# Message broker (see measurements/commands flow)
docker compose logs -f node_msg_broker

Stopping Services

docker compose down

Next Steps