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:

.. code-block:: bash

   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 :doc:`../examples/conflict_mitigation`).

Verify services are running:

.. code-block:: bash

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

Accessing the API
-----------------

The AIC Server provides a REST API and MCP endpoints:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **Health Check**: http://localhost:8000/health
- **List Apps**: http://localhost:8000/apps

Managing Applications
---------------------

List All Applications
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   curl http://localhost:8000/apps

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

.. code-block:: json

   {
     "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 :doc:`../user_guide/developing_plugins`.
See :doc:`../examples/conflict_mitigation` for the full pattern.

Start an Application
~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

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

Get Application State
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

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

Get Measurements
~~~~~~~~~~~~~~~~

.. code-block:: bash

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

Send a Manual Command
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   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``:

.. code-block:: python

   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:

.. code-block:: bash

   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
~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

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

Call a Tool
~~~~~~~~~~~

.. code-block:: bash

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

Viewing Logs
------------

.. code-block:: bash

   # 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
-----------------

.. code-block:: bash

   docker compose down

Next Steps
----------

- :doc:`configuration` — Learn about configuration options
- :doc:`../user_guide/developing_apps` — Create control applications
- :doc:`../user_guide/developing_nodes` — Build network nodes with the controlled_entity framework
- :doc:`../api/rest_api` — Full REST API reference
- :doc:`../api/mcp` — MCP integration details