respond

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 25, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package respond decides whether to speak, and how.

It sits between pkg/ingest, which knows about a socket, and pkg/answer, which knows about a corpus. Neither knows about the other: ingest reading a gateway is the thing that most needs to stay boring, and answering must remain usable from the CLI with no Discord anywhere near it. The decision to speak belongs to neither, so it lives here (spec 0010 D1).

Nothing posts by default. Shadow mode is the shipping state, not a test mode: everything runs, the answer is composed and recorded, and the thread stays empty until a person has read 30 answers to real questions and agreed they are worth posting (D6, D12).

Index

Constants

View Source
const (
	ReactionHelpful    = "👍"
	ReactionNotHelpful = "👎"
)

Feedback reactions (D9). Universally understood, need no explanation, and read as feedback on the message rather than on its subject — which ✅/❌ do not, since people already use those to mark a task done or a fact wrong.

View Source
const MaxMessageRunes = 1600

MaxMessageRunes is the largest message that will be posted.

Discord's own limit is 2000 characters; this sits under it so the citation block, which is appended after the prose is bounded, cannot push a message over. R-ANS-12 asks for a Discord-sane size with a link out rather than a wall of pasted code — the link is the citation, and it is never the part that gets truncated.

Variables

View Source
var ErrNoActor = errors.New("respond: provider has no actor to post through")

ErrNoActor means the platform provider cannot post.

Functions

This section is empty.

Types

type Asker

type Asker interface {
	Ask(ctx context.Context, question string) (answer.Response, error)
}

Asker is the answering path. pkg/answer.Service satisfies it.

An interface rather than the concrete service so this package can be tested without an index or a model, and so answering stays substitutable.

type Option

type Option func(*Service)

Option configures a Service.

func Live

func Live() Option

Live lifts shadow mode, so answers actually post.

Deliberately the option rather than the default. A misconfigured deployment that silently posts is worse than one that silently does not: the failure is visible to a public server rather than to an operator (D6).

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets the logger.

func WithThreads

func WithThreads(t Threads) Option

WithThreads overrides where opened threads are recorded.

type Posture

type Posture string

Posture is how an answer is presented, or that there is nothing to present.

Derived from the composer's outcome and its citation count (D4), never from a retrieval score — see answer.Outcome for why that signal was abandoned.

const (
	// PostureSilent means the bot was not addressed. Nothing was asked of it,
	// so nothing is composed and nothing is posted.
	PostureSilent Posture = "silent"

	// PosturePlain states the answer without qualification: either it rests on
	// more than one source, or it is a refutation, which the documentation
	// makes certain.
	PosturePlain Posture = "plain"

	// PostureHedged states the answer and says it rests on a single source.
	// Not a disclaimer bolted on — the reader is told what to go and check.
	PostureHedged Posture = "hedged"

	// PostureDecline says the corpus does not answer this, and what was
	// searched (D8). It posts: the bot was addressed directly, so silence
	// reads as broken.
	PostureDecline Posture = "decline"
)

The postures.

type Result

type Result struct {
	// Posture is what was decided. PostureSilent means not addressed.
	Posture Posture

	// Response is what the answering path produced. Zero when the bot was not
	// addressed, because nothing was asked.
	Response answer.Response

	// ThreadID is the thread the answer went in, empty in shadow mode where no
	// thread is created.
	ThreadID chatplatform.ID

	// Posted reports whether anything actually reached the platform. False in
	// shadow mode however complete the rest of the work was.
	Posted bool
}

Result is what Handle did, and why.

Returned rather than logged so a caller — the observer wiring, a test, the shadow review — can see the decision without parsing prose.

func (Result) Answered

func (r Result) Answered() bool

Answered reports whether this produced prose, as opposed to a decline or silence.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service decides whether to answer a message, and answers it.

func New

func New(a Asker, actor chatplatform.Actor, opts ...Option) (*Service, error)

New builds a responder.

The actor is a parameter rather than something discovered later (D7): a provider built read-only cannot post, and finding that out at the first attempt to answer means discovering it in front of a public server. Failing here fails at wiring, where an operator is watching.

func (*Service) Handle

func (s *Service) Handle(ctx context.Context, msg chatplatform.Message) (Result, error)

Handle decides whether to answer a message, and answers it.

This is the seam spec 0010 names for testing: one function taking a message and returning what was decided. Every decision the spec makes is observable through it — trigger matching, posture selection and the shadow split — so a test needs no other hook into this package.

An error means something broke. A question the corpus cannot answer is a Result with PostureDecline and no error, because a knowledge gap is an outcome rather than an incident (R-ANS-6c) and the gap backlog depends on telling them apart.

type ThreadSet

type ThreadSet struct {
	// contains filtered or unexported fields
}

ThreadSet is an in-memory Threads.

func NewThreadSet

func NewThreadSet() *ThreadSet

NewThreadSet returns the default in-memory record of opened threads.

In-memory is sufficient while shadow mode is the default, because nothing opens a thread. It is deliberately not sufficient afterwards: a restart forgets every thread, so a follow-up in one the bot opened before the restart stops being recognised as addressed to it. Persisting this belongs with the answer records rather than here.

func (*ThreadSet) MarkOpened

func (t *ThreadSet) MarkOpened(id chatplatform.ID)

MarkOpened records a thread the bot started.

func (*ThreadSet) Opened

func (t *ThreadSet) Opened(id chatplatform.ID) bool

Opened reports whether the bot started this thread.

type Threads

type Threads interface {
	// Opened reports whether the bot started this thread.
	Opened(id chatplatform.ID) bool

	// MarkOpened records a thread the bot has just started.
	MarkOpened(id chatplatform.ID)
}

Threads records which threads the bot opened.

It exists because D2's third trigger — a follow-up in a thread the bot started — cannot be answered from a message alone. A thread the bot did not open is somebody else's conversation, and replying in it uninvited is exactly the volunteering this spec declined.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL