Aiko Services

Distributed system framework supporting Machine Learning, Robotics, Media streaming and AIoT

Features

• Supports multi-nodal Machine Learning streaming pipelines ... that span from edge (embedded) devices all the way through to the data centre servers and back again

• Consistent distributed system approach integrating best-of-breed technology choices

  • Uses the Actor Model
  • Provides HyperSpace (example) ... a unified distributed Services graph for everything !
  • Uses Flow based programming via distributed Pipelines and PipelineElements
  • Provides low-latency performance with fully asynchronous function calls / method invocation via message passing

• Ease of visualization and diagnosis for systems with many interconnected components via the Aiko Dashboard

• Light-weight, extensible core design for performance on high-end servers ... and supports operation on embedded devices, i.e a micro-controller reference implementation, e.g ESP32 running microPython

• Flexible deployment choices when deciding which components should run in the same process (for performance) or across different processes and/or hosts (for flexibility)

• Aims to make the difficult challenges much easier !

Documentation

• Design overview
• Concepts guide 👀
• Pipeline and PipelineElements guide
• Examples reference
• Release notes

Uses the Open Knowledge Format ... and so the documentation is immediately useable by your favorite A.I coding assistant 🤖

See the Wiki for Glossary (concepts), Roadmap for v1.0, Work In Progress (WIP) and Reference pages

Installation

Installing from PyPI (Python Package Index)

Recommended when simply trying Aiko Services by using existing examples and tools.

Installs the Aiko Services package from PyPI

pip install aiko_services

Installing from GitHub for developers

Recommended when using Aiko Services as a framework for development

git clone https://github.com/geekscape/aiko_services.git
cd aiko_services
python3 -m venv venv      # Once only
source venv/bin/activate  # Each terminal session
pip install -U pip        # Install latest pip
pip install -e .          # Install Aiko Services for development

Installing for package maintainers

Recommended when making an Aiko Services release to PyPI

Before building, ensure that the release version has been updated and committed in both of these files ...

• src/aiko_services/__init__.py ... __version__ and __id__
• pyproject.toml ... version (used by Hatch for the package version)

Important: Always build from a fresh git clone, never from a development working tree. Hatch bundles all directory contents into the package, so any untracked local files, e.g media files or back-up copies, would be included

git clone https://github.com/geekscape/aiko_services.git aiko_services_release
cd aiko_services_release
python3 -m venv venv      # Once only
source venv/bin/activate  # Each terminal session
pip install -U pip        # Install latest pip
pip install -U hatch      # Install latest Hatch build and package manager
# hatch test              # Run local tests (to be completed)
hatch build               # Build Aiko Services package: dist/*.whl and dist/*.tar.gz

Check that the build output is correct, i.e the wheel should be well under 1 MB and only contain source code (plus a few small sample data files)

unzip -l dist/aiko_services-*.whl

Publishing to PyPI requires a PyPI API token scoped to the aiko-services project ... username / password uploads are no longer supported by PyPI

HATCH_INDEX_USER=__token__ HATCH_INDEX_AUTH=pypi-YOUR_API_TOKEN  \
  hatch publish dist/   # Publish Aiko Services package to PyPI

Quick start

After installing (above), choose whether to use a public MQTT server ... or to install and run your own MQTT server

It is easier to start by using a public remotely hosted MQTT server to tryout a few examples.

For the longer term, it is better and more secure to install and run your own MQTT server.

Running your own mosquitto (MQTT) server

• Install the mosquitto (MQTT) server on Linux, Mac OS X or Windows

On Linux or Mac OS X: Start mosquitto, aiko_registrar and aiko_dashboard

./scripts/system_start.sh  # default AIKO_MQTT_HOST=localhost

Examples

• Aloha Honua examples ... Hello world Actor
• HyperSpace example ... Unified distributed Services graph

Package	Contents
aloha_honua/	The graduated four-stage hello-world Actor tutorial — plain Actor, discovery client, remote stop, request/response
pipeline/	Teaching Pipelines — local vs remote deployment, Graph Paths, frame data encode/decode, plus the multitude/ scale stress tests
colab/	Google Colab integration — running Pipelines inside a notebook with browser camera, microphone and speaker widgets
speech/	Speech processing — microphone capture, WhisperX transcription, Coqui text-to-speech and the speech-to-LLM round trip
llm/	Large Language Model elements — LangChain over Ollama or OpenAI, driven by the speech pipelines or a terminal
yolo/	YOLOv8 and YOLOE open-vocabulary object detection Pipelines
aruco_marker/	ArUco fiducial marker detection and overlay
face/	Face detection using DeepFace, with shared detection counters
robot/	Robot OODA-loop elements and the Panda3D virtual robot world
xgo_robot/	XGO-Mini 2 robot dog — on-robot Actor, laptop-side remote control and video monitor
system_pipelines/	System bootstrap via ProcessManager and the distributed webcam-to-YOLOE Pipeline pair

To Do

See GitHub Issues

Presentations

• An open-source framework for creating awesome Machine Learning applications

  • Slide deck (Google slides)
  • Everything Open conference January 2025: Adelaide, Australia

• microPython distributed, embedded services (YouTube)

  • Slide deck (Google slides)
  • microPython meet-up November 2023: Melbourne, Australia

• Using Python to stream media using GStreamer for RTSP and WebRTC applications (YouTube)

  • Slide deck (Google slides)
  • PyCon AU conference August 2023: Adelaide, Australia

• Building an open framework combining AIoT, Media, Robotics & Machine Learning (YouTube)

  • Slide deck (Google slides)
  • Everything Open conference March 2023: Melbourne, Australia