Platform Core

Project Overview

Promethist Core projects implements a runtime for relational AI agents. Its main part is the engine — a reactive Spring Boot application that executes a conversation inside an interaction pipeline: it recognizes speech, drives a language model with the agent’s instructions, memory and tools, synthesizes the reply and streams it back to the client in real time.

This documentation covers the platform repository: what the individual modules are, how to build and run them, how the engine is put together internally, and how a deployment is operated.

Module Structure

Dependencies between the Promethist Gradle modules
Figure 1. Gradle modules and their dependencies

An arrow points from a module to what it depends on:

  • lib is the foundation — the wire protocol types, media utilities and storage abstractions. It depends on nothing.

  • common and client are siblings, each depending only on lib. client does not depend on common.

  • engine and bridge are applications and depend on client, common and lib.

  • relay is a standalone service with no module dependencies at all.

  • common is additionally published as the promethist-common Maven artifact, which the platform backend service in its own repository builds against — so its public types are a shared contract beyond this repository.

Modules describes each module and the build layout in detail.

Documentation Map

Modules

The Gradle modules in this repository, what each is for and how they depend on each other.

Technology Stack

Languages, frameworks and the external services the platform needs at runtime — with the role each of them plays.

Development Setup

Prerequisites, building, running the engine locally, running tests, the local infrastructure stack and the local port map.

Core Deployment

How container images are built and released, and how the core services are deployed with the Helm charts in deploy/.

Code Conventions

Formatting rules and the KtLint tooling, including the pre-commit hook.

Engine Application

Internal architecture of the engine: pipeline, components, services, controllers, AI layer, sockets and security.

Common Library

The shared library: domain model, pipeline abstractions, memory, AI abstractions, storage and serialization.

Bridge Application

The automated conversation testing service — how to run tests against real devices, browsers and virtual agents.

Reference CLI Client

The command-line reference client, useful for exercising the conversation protocols by hand.

Core Documentation

The official public-facing documentation of the platform core — the engine’s REST API and the conversation protocols — intended for third-party developers.

Building This Documentation

The documentation is an Antora component. Its sources live in docs/; the site is assembled by the playbook antora-playbook.yml in the repository root:

npx antora antora-playbook.yml

The generated site is written to build/site. API reference documentation for the Kotlin code is generated separately with Dokka:

./gradlew dokkaHtmlMultiModule

In this section