V1.1.0

agent.rst

@@ -18,3 +18,31 @@ The QUANT-NET Agent that registers resources, interfaces with devices, and inter
    :prog: quantnet_agent
    :nested: full
 
+Monitoring Events
+-----------------
+
+The agent scheduler publishes ``MonitorEvent`` messages to the ``monitor``
+topic as tasks complete. Each event includes:
+
+- ``eventType``: ``"agentTaskResult"`` — identifies the message as a local
+  task result (distinct from a full experiment result).
+- ``value.name``: the task name.
+- ``value.exp_id``: the experiment/task ID, used by the controller to
+  correlate results when queried via ``getTasks``.
+- ``value.result``: the task result payload (when present).
+
+Configuration
+-------------
+
+The agent reads its configuration from an INI file. A path can be provided
+explicitly with the ``-c``/``--config`` CLI flag; if the file does not exist
+the agent exits immediately with an error.
+
+Without ``-c``, the config path depends on the environment:
+
+ * If ``$QUANTNET_HOME`` is set: ``$QUANTNET_HOME/etc/agent.cfg``
+ * Otherwise: ``/etc/quantnet/agent.cfg``
+
+If no config file is found the agent continues with defaults and logs a
+warning. Message broker log output is suppressed to warning level by default.
+

api.rst

@@ -0,0 +1,286 @@
+Northbound API
+##############
+
+.. pypi-shield::
+    :project: quantnet-api
+    :version:
+
+
+.. github-shield::
+    :last-commit:
+    :repository: qn-api
+    :branch: main
+
+
+The northbound API server provides a RESTful interface for external applications to interact with the QUANT-NET control plane. It exposes endpoints for querying topology information, submitting experiments, and retrieving results. The API is designed to be intuitive and easy to use, enabling seamless integration with third-party tools and dashboards.
+
+
+Running the API Server
+----------------------
+
+CLI
+~~~
+
+When installed as a package (``pip install quantnet-api``), the ``qn-api``
+console script is available:
+
+.. code-block:: console
+
+   $ qn-api --help
+   usage: qn-api [-h] [--host HOST] [--port PORT] [--reload]
+
+   Run the Quant-Net API
+
+   options:
+     -h, --help   show this help message and exit
+     --host HOST  Host to bind (default: 0.0.0.0)
+     --port PORT  Port to bind (default: 8081)
+     --reload     Enable auto-reload on file changes (development only)
+
+Examples:
+
+.. code-block:: console
+
+   # Start on the default host/port (0.0.0.0:8081)
+   $ qn-api
+
+   # Bind to localhost on port 9000
+   $ qn-api --host 127.0.0.1 --port 9000
+
+   # Development mode with auto-reload
+   $ qn-api --reload
+
+Alternatively, you can run the module directly with ``uvicorn``:
+
+.. code-block:: console
+
+   $ uvicorn main:app --host 0.0.0.0 --port 8081 --reload
+
+Docker
+~~~~~~
+
+For containerised deployments, the
+`qn-docker <https://github.com/quant-net/qn-docker>`_ repository provides a
+``docker-compose.yml`` that orchestrates the API server alongside the
+Controller, agents, message broker, and database in a single test stack.
+Refer to the ``qn-docker`` README for setup instructions.
+
+Web Portal (Dashboard)
+~~~~~~~~~~~~~~~~~~~~~~
+
+The API server includes a web dashboard for interactive exploration of the network topology, agent calibration tasks, and experiment management. The dashboard is accessible at the root URL (``/``) when the server is running. 
+
+.. image:: _static/web-dashboard.png
+  :width: 600
+  :alt: Screenshot of the web dashboard
+
+
+Configuration File
+------------------
+
+The API server reads the same INI-style configuration file used by the
+:doc:`Controller </server>`. The following paths are probed in order:
+
+* ``$QUANTNET_HOME/etc/quantnet.cfg``
+* ``$VIRTUAL_ENV/etc/quantnet.cfg``
+* ``/opt/quantnet/etc/quantnet.cfg``
+
+If no file is found the server logs a warning and continues with built-in
+defaults.
+
+Example (API-relevant sections only): ::
+
+  [mq]
+  host = 127.0.0.1
+  port = 1883
+  mongo_host = 127.0.0.1
+  mongo_port = 27017
+  ws_host = 127.0.0.1
+  ws_port = 8080
+  rpc_server_topic = quantnet/rpc/server
+  rpc_client_topic = quantnet/rpc/client
+
+  [schemas]
+  path = /opt/qn-plugins/schema
+
+  [main]
+  request_types = ["spgRequest", "egpRequest", "bsmRequest"]
+
+
+[mq]
+====
+
+.. confval:: api_mq_host
+
+   :type: string
+   :default: ``127.0.0.1``
+
+   The MQTT broker host used for RPC communication with the Controller.
+
+.. confval:: api_mq_port
+
+   :type: string
+   :default: ``1883``
+
+   The MQTT broker port.
+
+.. confval:: api_mongo_host
+
+   :type: string
+   :default: ``127.0.0.1``
+
+   The MongoDB host used by the message bus layer.
+
+.. confval:: api_mongo_port
+
+   :type: string
+   :default: ``27017``
+
+   The MongoDB port used by the message bus layer.
+
+.. confval:: api_ws_host
+
+   :type: string
+   :default: ``127.0.0.1``
+
+   The WebSocket host exposed to the web dashboard for live updates.
+
+.. confval:: api_ws_port
+
+   :type: string
+   :default: ``8080``
+
+   The WebSocket port exposed to the web dashboard.
+
+.. confval:: rpc_server_topic
+
+   :type: string
+
+   The MQTT topic the Controller listens on for RPC requests.
+
+.. confval:: rpc_client_topic
+
+   :type: string
+
+   The MQTT topic the API subscribes to for RPC responses.
+
+.. confval:: api_mq_path
+
+   :type: string
+
+   Optional filesystem path used by the message bus layer.
+
+[schemas]
+=========
+
+.. confval:: api_schema_path
+
+   :type: string
+
+   Path to a directory of YAML schemas conforming to the :doc:`Message Bus </comms>` spec.
+   When set, schemas are loaded at startup so the RPC client can validate
+   messages.
+
+[main]
+======
+
+.. confval:: request_types
+
+   :type: list
+   :default: ``["spgRequest", "egpRequest", "bsmRequest"]``
+
+   The experiment request types surfaced in the web dashboard's request
+   submission form.
+
+
+FastAPI Application
+-------------------
+
+The application is defined in ``main.py`` and assembled from the components
+described below.
+
+Router & Endpoints
+~~~~~~~~~~~~~~~~~~
+
+All REST endpoints are grouped under the ``/api`` prefix via a dedicated
+``APIRouter``. The table below summarises the available routes:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 10 30 60
+
+   * - Method
+     - Path
+     - Description
+   * - GET
+     - ``/api/topology``
+     - Retrieve the network topology graph. Pass ``?full=true`` for complete
+       node definitions including channel data.
+   * - GET
+     - ``/api/node``
+     - List all nodes in the network.
+   * - GET
+     - ``/api/node/{ID}``
+     - Get information for a specific node by its identifier.
+   * - GET
+     - ``/api/experiments``
+     - List all experiments. Supports ``?last=true``, ``?request=true``, and
+       ``?agent_id=<id>`` query parameters.
+   * - GET
+     - ``/api/experiments/{expid}``
+     - Get a specific experiment by ID.
+   * - GET
+     - ``/api/calibration``
+     - List all calibrations. Supports ``?last=true``.
+   * - GET
+     - ``/api/calibration/{calid}``
+     - Get a specific calibration by ID.
+   * - GET
+     - ``/api/tasks``
+     - Get agent task results. Supports ``?agent_id=<id>``.
+   * - POST
+     - ``/api/pingpong``
+     - Send ping requests to a list of remote nodes.
+       Parameters: ``remotes`` (list), ``iterations`` (int, default 5).
+   * - POST
+     - ``/api/calibrate``
+     - Run a calibration process.
+       Parameters: ``type``, ``src``, ``dst``, ``power``, ``light``.
+   * - POST
+     - ``/api/bsm``
+     - Start a BSM experiment.
+       Parameters: ``src`` (list), ``rate`` (float), ``duration`` (float).
+   * - POST
+     - ``/api/spg``
+     - Start a single-photon generation experiment.
+       Parameters: ``src`` (list), ``rate`` (float), ``duration`` (float).
+   * - POST
+     - ``/api/egp``
+     - Start an entanglement generation experiment.
+       Parameters: ``src``, ``dst``, ``pairs``, ``bellState``, ``fidelity``.
+
+Interactive API documentation is auto-generated by FastAPI and available at
+``/docs`` (Swagger UI) and ``/redoc`` (ReDoc) when the server is running.
+
+Error Handling
+~~~~~~~~~~~~~~
+
+Every endpoint delegates to a centralised ``_rpc_request`` helper that wraps
+the underlying RPC call with uniform error handling:
+
+* **504 Gateway Timeout** — returned when the Controller does not respond
+  within the RPC timeout window (default 10 s).
+* **502 Bad Gateway** — returned for any other communication failure with the
+  Controller.
+
+Both responses include a JSON body with ``error`` and ``detail`` fields.
+
+
+OpenAPI Schema
+~~~~~~~~~~~~~~
+
+A custom OpenAPI schema is generated at startup with the title
+**Quant-Net API**. The interactive documentation is served at:
+
+* ``/docs`` — Swagger UI
+* ``/redoc`` — ReDoc

comms.rst

@@ -168,3 +168,46 @@ We may then load and use the schema objects directly using ``quantnet_mq``:
     >>> req.serialize()
     '{"cmd": "myRequest", "agentId": "agent1", "payload": {"arg1": "Hello", "arg2": 99.99}, "agentID": "agent1", "command": "myRequest"}'
     >>>
+
+
+EventType Enum
+**************
+
+``quantnet_mq`` exports an ``EventType`` string enum that provides typed constants
+for all monitor event types used across the control plane:
+
+.. code-block:: python
+
+    from quantnet_mq import EventType
+
+    EventType.AGENT_STATE               # "agentState"
+    EventType.EXPERIMENT_RESULT         # "experimentResult"
+    EventType.AGENT_HEARTBEAT           # "agentHeartbeat"
+    EventType.AGENT_TASK_SCHEDULER_PHASE  # "agentTaskSchedulerPhase"
+    EventType.AGENT_TASK_SCHEDULER_TASK   # "agentTaskSchedulerTask"
+    EventType.AGENT_TASK_RESULT         # "agentTaskResult"
+
+These constants correspond directly to the ``eventType`` field of
+``MonitorEvent`` messages published to the ``monitor`` topic.
+See :doc:`Monitoring </monitoring>` for descriptions of each event type.
+
+Built-in Server RPC Schemas
+****************************
+
+qn-mq ships a set of built-in RPC message types used between agents and the
+controller. Notable additions:
+
+**MonitorTask / MonitorTaskResponse** — enables clients to query recorded
+agent task results from the controller's Monitor database via a ``getTasks``
+RPC call. The request may include an optional agent filter.
+See :doc:`Monitoring </monitoring>` for full details.
+
+Core Object Schemas
+*******************
+
+The core schema bundled with qn-mq provides common object types reusable in
+user-defined schemas. Recent additions:
+
+- ``Channel.length`` — a numeric property added to the ``Channel`` schema,
+  exposing quantum channel length. When the controller topology API is queried
+  in full mode, this field appears within each node's channel data.

contributing.rst

@@ -64,6 +64,6 @@ Before you submit a pull request, check that it meets these guidelines:
 2. Code should adhere to PEP8 style guidelines.
 3. If the pull request fixes a bug, the description should include a
    description of the bug and how the fix addresses it.
-3. If the pull request adds functionality, the docs should be updated. Put
+4. If the pull request adds functionality, the docs should be updated. Put
    your new functionality into a function with a docstring and add a README.