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 ¶
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.
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 ¶
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 ¶
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 WithThreads ¶
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.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service decides whether to answer a message, and answers it.
func New ¶
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 ¶
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.
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.