Development Setup

This guide covers setting up a development environment for ai_nn_controller.

Prerequisites

Python 3.9 or newer
Docker and Docker Compose
Git

Setting Up

Clone the repository:

git clone https://github.com/merimdzaferagic/ai_nn_controller.git
cd ai_nn_controller

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install the framework in development mode:

cd controller_components/ai_nn_controller
pip install -e ".[dev]"

Install additional dependencies:

pip install pyzmq fastapi uvicorn pydantic redis requests sse-starlette

Running Services

Start infrastructure services:

docker compose up -d redis aic_register node_msg_broker

Run the example application locally:

cd control_applications/control_application_v2_example
python aic_app.py --verbose

Project Structure

.
├── control_applications/
│   └── control_application_v2_example/  # Reference control application
├── network_nodes/
│   ├── dummy_nodes/        # Simulated test nodes
│   ├── srsran_node/        # srsRAN 5G RAN integration (InfluxDB bridge)
│   └── twilight_nodes/     # Twilight optical network bridge nodes
├── fastapi_client/         # Python client for the AIC REST API
└── controller_components/
    ├── ai_nn_controller/   # Core framework (editable install)
    │   ├── AicApp.py
    │   ├── AicController.py
    │   ├── decorators/
    │   ├── managers/
    │   ├── mcp/
    │   ├── protocol/
    │   └── ...
    ├── controlled_entity/  # Node-side framework
    ├── register/           # Registration service
    └── node_msg_broker/    # Message broker

Development Workflow

Make changes to framework code in ai_nn_controller/
Test locally with a simple application
Run tests with pytest
Format code with black and isort
Build Docker images if needed
Test with Docker Compose

Running Tests

# Run all tests
pytest controller_components/

# Run with coverage
pytest --cov=ai_nn_controller controller_components/

# Run specific test file
pytest controller_components/tests/test_registry.py

Code Formatting

# Format code
black controller_components/

# Sort imports
isort controller_components/

# Type checking
mypy controller_components/ai_nn_controller/

Building Documentation

cd docs
pip install -r requirements.txt
make html

# Live preview
make livehtml

View documentation at docs/_build/html/index.html

Debugging

Enable verbose logging:

AicController(with_api=True, verbose=True).run()

Or via command line:

python aic_app.py --verbose

View Docker logs:

docker compose logs -f aic_server
docker compose logs -f node_msg_broker

Common Issues

ZMQ Connection Errors

Ensure infrastructure is running:

docker compose ps

Import Errors

Install the framework:

cd controller_components/ai_nn_controller
pip install -e .

Port Conflicts

Check for processes using required ports:

lsof -i :8000
lsof -i :5558