#+TITLE: Orator - OpenAI API to ActivityPub Gateway

Orator converts between OpenAI-like APIs (OpenResponses, ChatCompletion) and ActivityPub federation protocol, enabling AI agents to communicate via ActivityPub.

• Overview

  #+begin_src crystal #+name: orator require "translator" require "translator/registry"

  settings do data.adapter = "memory" port = 8080 end

  struct InputSchema include Api::OpenResponses::Request include Api::ChatCompletionAPI::Request include Api::Models end

  struct OutputSchema include Api::OpenResponses::Response include Api::ChatCompletionAPI::Response end

  @[Container(static)] @[Load(".env")] @[Validate(InputSchema, OutputSchema)] workflow "orator" do follow ["@actra@lefine.pro"]

  send_to_inbox

  recevie_from_outbox end #+end_src

• Architecture

  #+begin_src ┌─────────────────┐ │ OpenAI Request │ (POST /v1/responses or /v1/chat/completions) │ OpenResponses │ │ ChatCompletion │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ send_to_inbox │ Convert to ActivityPub Create{Ticket} └────────┬────────┘ │ ▼ ┌─────────────────┐ │ ActivityPub │ ForgeFed Ticket via Aptok │ Inbox/Outbox │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ receive_from_ │ Convert back to OpenAI format │ outbox │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ OpenAI Response │ │ OpenResponses │ │ ChatCompletion │ └─────────────────┘ #+end_src

• Components

  ** translators/

  • converters.cr - OpenAI ↔ ActivityPub conversion logic
  • translators.cr - Ocawe node kind implementations (SendToInbox, ReceiveFromOutbox)
  • registry.cr - Registers custom node kinds with Ocawe::RegistryApi.node_kind()

  Uses Aptok helpers: Aptok.forgefed_ticket() and Aptok.create()

• Usage

  #+begin_src shell cd orator ocawe up #+end_src

  Then send requests to:

  • GET http://localhost:8080/v1/models - List available models
  • POST http://localhost:8080/v1/responses - OpenResponses format
  • POST http://localhost:8080/v1/chat/completions - ChatCompletion format

• Requirements

  • Ocawe framework (workflows, federation, node registry)
  • Aptok library (ActivityPub helpers)

• Deployment

  ** Container

  The project includes GitHub Actions CI/CD to build and publish containers:

  #+begin_src shell

  Pull from GitHub Container Registry

  docker pull ghcr.io/lefinepro/orator:latest

  Run the container

  docker run -p 8080:8080 ghcr.io/lefinepro/orator:latest #+end_src

  ** Building Locally

  #+begin_src shell

  Build with ocawe CLI

  ocawe build --release --output build/ocawe

  Build Docker image

  docker build -t orator:latest . #+end_src

  ** CI/CD

  The =.github/workflows/container.yml= workflow automatically:

  • Builds multi-platform containers (linux/amd64, linux/arm64)
  • Publishes to GitHub Container Registry
  • Creates tags for branches, PRs, and semantic versions