Skip to content

modules.md

Latest commit

 

History

History
80 lines (58 loc) · 4.37 KB

modules.md

File metadata and controls

80 lines (58 loc) · 4.37 KB
Raw

Module Responsibilities

Ingest (Discord)

The ingest module receives Discord DM messages, distinguishes command versus capture paths, and writes a raw event record before downstream processing. If raw event writes fail, the pipeline stops for that message.

Interpreter (LLM)

The interpreter triages messages, extracts structured fields, and emits strict-schema derived JSON artifacts. When update/append routing is enabled, capture interpretation becomes candidate-aware and proposes create/update/append operations in the same strict-schema response. Validation failures write invalid artifacts and return clarification responses without mutating canonical state. OpenAI transport is async-native in runtime message handling; async interpreter paths await provider calls directly and fall back to off-loop execution only for providers without async methods.

Store (Git Canonical Store)

The store applies create/update/append operations to canonical markdown objects with schema validation and audit linkage (source_event_ids, last_decision_id). Operations run sequentially, and apply failures halt further processing for that message while surfacing the error to the user.

Index (SQLite)

The index parses canonical objects and builds derived SQLite search tables (objects, objects_fts). When semantic matching is enabled, semantic rows/metadata are also maintained in the same database. The index is rebuildable from canonical objects and is not authoritative state.

Surfacer

The surfacer provides push (scheduled daily/weekly digest/review) and pull (interactive commands), with configurable ID visibility for scheduled outputs and ID-inclusive manual pull lists. Numbered outputs replace the current conversation-root cursor so follow-up commands can target them. It is read-only and does not mutate canonical state.

Shared Transport Runtime

Shared transport modules own transport-agnostic runtime behavior (for example command orchestration, NL routing/normalization, cursor/clarification state handling, and reminder scheduling helpers).

These modules are intended to be reused across Discord and future interfaces (for example Slack).

Transport Adapters

Adapters are responsible for platform-specific concerns only:

  1. event ingestion and platform identity/channel resolution
  2. platform message send/edit/reaction/action mechanics
  3. platform UI components and scheduler loop wiring

Design rules:

  1. keep transport SDK imports in adapter modules
  2. keep shared runtime logic transport-neutral
  3. use adapter-to-shared contracts instead of passing SDK-native objects into shared layers

Current Discord adapter/runtime split:

  1. /Users/dblinkhorn/squire/src/squire_core/transport/discord/adapter.py: event translation (discord.Client lifecycle hooks) and Discord message/reaction IO helpers.
  2. /Users/dblinkhorn/squire/src/squire_core/transport/discord/views.py: Discord UI views (PendingActionView, MutationPendingView, AutoApplyFeedbackView) and interaction callbacks.
  3. /Users/dblinkhorn/squire/src/squire_core/transport/discord/scheduler.py: digest/reminder scheduling loops and Discord delivery channel resolution.
  4. /Users/dblinkhorn/squire/src/squire_core/transport/discord/context.py: Discord message-to-contract translation (TransportMessageContext).
  5. /Users/dblinkhorn/squire/src/squire_core/transport/discord/io.py: Discord send/reaction IO wrappers over adapter primitives.
  6. /Users/dblinkhorn/squire/src/squire_core/transport/discord/runtime.py: Discord runtime entrypoint used by /Users/dblinkhorn/squire/src/squire_core/runtime.py.
  7. /Users/dblinkhorn/squire/src/squire_core/transport/discord/runtime_adapter_{command,routing,inbound}.py: Discord adapter bridge implementations for command/routing/inbound runtime protocols, with injected RuntimeStateStore state seams.
  8. /Users/dblinkhorn/squire/src/squire_core/transport/discord/message_entry.py: Discord message ingress handlers (command dispatch, NL-route dispatch, and DELETE archive-clear confirmation handling).
  9. /Users/dblinkhorn/squire/src/squire_core/runtime.py: transport-agnostic composition entrypoint that delegates to a selected transport runtime via transport/runtime_registry.py.

Optional Providers

Current runtime ships with Discord ingest and OpenAI model provider integration. Additional providers or ingest interfaces are not currently available and require explicit implementation.