Stargazer v3 — Technical Documentation
=======================================

.. image:: https://img.shields.io/badge/python-3.12-blue.svg
   :alt: Python 3.12

Architectural Overview
----------------------

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

System Architecture
^^^^^^^^^^^^^^^^^^^

The system is organized into the following layers:

**Entry Point & Lifecycle** — :mod:`main` boots the :class:`~main.BotRunner`, which
manages multi-platform adapter lifecycles, message routing, and the web management GUI.

**Platform Adapters** — The :mod:`platforms` package provides a
:class:`~platforms.base.PlatformAdapter` interface implemented by
:mod:`platforms.discord` and :mod:`platforms.matrix`. Adapters normalize incoming
messages into :class:`~platforms.base.IncomingMessage` objects and expose a uniform
reply API.

**Message Processing Pipeline** — :mod:`message_processor` is the core orchestrator.
For each incoming message it:

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

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

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

- :mod:`limbic_system` — Core neurochemical vector state machine
- :mod:`cascade_engine` — Multi-turn event cascades
- :mod:`ncm_engine` — Top-level NCM orchestrator
- :mod:`ncm_desire_engine` — Desire/motivation modeling
- :mod:`ncm_semantic_triggers` — Semantic trigger evaluation
- :mod:`cadence_refiner` — Response cadence and style adjustment
- :mod:`user_limbic_mirror` — Per-user affective modeling

**Knowledge & Memory** — Long-term memory and knowledge management:

- :mod:`knowledge_graph` — FalkorDB-backed knowledge graph
- :mod:`rag_system` — RAG pipeline with embedding search
- :mod:`message_cache` — Redis-backed message history
- :mod:`threadweave` — Multi-thread conversation management

**Background Processing** — Async agents in :mod:`background_agents`:

- :mod:`background_agents.channel_summarizer` — Automatic channel summaries
- :mod:`background_agents.research_agent` — Background research tasks
- :mod:`background_agents.deep_think_agent` — Extended reasoning

**Configuration** — :mod:`config` loads ``config.yaml`` with environment variable
overrides, supporting per-platform settings.


API Reference
-------------

.. toctree::
   :maxdepth: 2
   :caption: Core Modules

   api/core/modules

.. toctree::
   :maxdepth: 2
   :caption: Tools

   api/tools/modules

.. toctree::
   :maxdepth: 2
   :caption: Classifiers

   api/classifiers/classifiers

.. toctree::
   :maxdepth: 2
   :caption: Platform Adapters

   api/platforms/platforms

.. toctree::
   :maxdepth: 2
   :caption: RAG System

   api/rag_system/rag_system

.. toctree::
   :maxdepth: 2
   :caption: Background Agents

   api/background_agents/background_agents


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`