Stargazer v3 — Technical Documentation

Architectural Overview

Stargazer v3 is a multi-platform conversational AI bot that bridges Discord, Matrix, and WebChat with a shared LLM inference pipeline, an extensible tool-calling framework, and a neurochemical simulation engine for affective computing.

As of the Phase T3 migration (2026-06-02) the original main.BotRunner monolith has been retired. Stargazer now runs as five independent microservices that communicate over Redis Streams. Each boots from the shared StargazerService contract and exposes /healthz and /readyz probes via HealthServer.

Services

Gateway (gateway_main) — the only service that holds live platform connections. It runs a PlatformAdapter for each enabled platform, normalizes inbound events into IncomingMessage objects, wraps each in a validated InboundEnvelopeModel, and publishes it to the sg:stream:inbound stream. It also consumes the per-platform sg:stream:outbound:{platform} streams and dispatches replies back through the real adapters.

Inference (inference_main) — the stateless, horizontally scalable LLM worker. It consumes sg:stream:inbound (consumer group sg:workers) under a per-channel DistributedLock, reconstructs the message, and runs the full MessageProcessor pipeline — sending every reply through a ProxyPlatformAdapter that publishes to the outbound streams instead of calling a platform SDK directly.

Agents (agents_main) — recurring/background work (knowledge-graph extraction and summarization, limbic/NCM upkeep, scheduled prompts, optional game/dyadic agents, SWORD, StarWiki), guarded by a cluster-singleton TaskSupervisor so each job runs on exactly one node.

Consolidation (consolidation_main) — long-horizon knowledge-graph consolidation and decay, isolated so this slow, LLM-heavy work scales and restarts independently of the request path.

Web (web_main) — the FastAPI management dashboard and StarWiki, serving operational state without booting message processing.

Message flow

A single user message traverses the services as follows:

Platform event
  → Gateway: PlatformAdapter → IncomingMessage
  → _make_inbound_envelope() → InboundEnvelopeModel
  → RedisEventBus.publish_inbound() → sg:stream:inbound
  → Inference: InboundStreamConsumer (group sg:workers, per-channel lock)
  → _incoming_message_from_envelope() → IncomingMessage
  → MessageProcessor.handle_message(msg, ProxyPlatformAdapter)
      · preprocess · classify tools · gather RAG/web/context · build prompt
      · OpenRouterClient.chat() (tool-call loop) · response postprocessing
  → ProxyPlatformAdapter.send() → RedisEventBus.publish_outbound()
  → sg:stream:outbound:{platform}
  → Gateway: OutboundStreamConsumer → real PlatformAdapter.send()
  → Platform

Shared infrastructure — the `core` package

The core package holds the runtime every service shares:

core.service_base — the StargazerService boot/shutdown contract and health-server wiring
core.event_bus — RedisEventBus (Redis Streams publish/consume of sg:stream:inbound / sg:stream:outbound:{platform})
core.stream_consumer and core.outbound_consumer — inbound and outbound consumer-group readers with XAUTOCLAIM crash recovery
core.proxy_adapter — worker-side PlatformAdapter shim that turns sends into outbound events and relays gateway-pinned tools back to the Gateway
core.serialization — msgpack envelope models (InboundEnvelopeModel, OutboundEnvelopeModel)
core.distributed_lock — watchdog-renewed per-channel locks
core.trace and core.state_machine — trace IDs and crash-safe per-operation state with checkpoints
core.health_server — /healthz and /readyz probes
core.dlq — dead-letter queue for poison messages

Platform Adapters

The platforms package provides a PlatformAdapter interface implemented by platforms.discord, platforms.matrix, and platforms.webchat. Adapters normalize incoming messages into IncomingMessage objects and expose a uniform reply API. They run inside the Gateway; the Inference worker sees the same interface via the ProxyPlatformAdapter.

Message Processing Pipeline

Inside the Inference worker, message_processor orchestrates each message. For each incoming message it:

Preprocesses (URL extraction, attachment handling, multimodal parts)
Resolves conversation history via conversation and message_cache
Classifies and selects relevant tools via classifiers.vector_classifier
Gathers RAG context from rag_system
Builds the LLM prompt with prompt_context and prompt_renderer
Calls the LLM via openrouter_client
Postprocesses the response with response_postprocessor

Tool Framework — tools provides the ToolRegistry decorator system. Each tool file in the tools/ directory is auto-loaded by tool_loader. Tools are async callables that receive an optional ToolContext for bot-internal access. The classifiers.vector_classifier selects tools per-message via semantic embedding similarity.

Neurochemical Model (NCM) — An affective computing layer that simulates neurochemical states: