respond

package
v0.4.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: 15 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 DefaultRetention = 180 * 24 * time.Hour

DefaultRetention is how long a question is kept.

180 days rather than the 30 the rest of the policy uses (spec 0010 D5a). Low volume is exactly when a short window destroys the signal: a handful of questions a week expiring at 30 days never accumulates enough to rank a documentation gap. It reduces to 30 once traffic makes the shorter window sufficient, and the published policy commits to that reduction rather than leaving 180 to become permanent by default.

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.

View Source
const SelfUser chatplatform.ID = "__self__"

SelfUser is the user id standing for the bot itself.

The bot reacts to its own answers to offer the feedback affordance, and those reactions arrive back through the same path a person's do. Counting them would give every answer one vote from itself.

Variables

View Source
var ErrNoActor = errors.NewSentinel("respond.no_actor", "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 WithRecorder added in v0.4.0

func WithRecorder(r *Recorder) Option

WithRecorder persists every answer and the feedback on it.

Optional, so this package stays usable without a database — but a deployment without one cannot clear D12's gate, because there is nothing to review.

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 Question added in v0.4.0

type Question struct {
	ID      int64
	TopicID int64
	Text    string
	Lang    string
	// MatchScore is the BM25 score this question's topic was decided on, and
	// zero where nothing was compared. Recorded so matchFloor can eventually be
	// chosen from evidence instead of measurement on a handful of rows.
	MatchScore float64
	AskedAt    time.Time
}

Question is one asking, as stored.

type Record added in v0.4.0

type Record struct {
	Question  string
	UserID    chatplatform.ID
	ChannelID chatplatform.ID
	ThreadID  chatplatform.ID

	// MessageID is the bot's own posted message, which is what a reaction
	// arrives against. Empty in shadow mode, where nothing was posted and so
	// nothing can be reacted to.
	MessageID chatplatform.ID

	Outcome   answer.Outcome
	Posture   Posture
	Citations int
	Posted    bool
}

Record is one answer, as the caller describes it.

Question and UserID are the raw values. They are hashed on the way in and never stored — see Recorder.Record.

type Recorder added in v0.4.0

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

Recorder persists answers and the feedback on them.

It holds the deployment salt, which is why it is constructed rather than being a set of free functions over a database.

func NewRecorder added in v0.4.0

func NewRecorder(ctx context.Context, db *store.DB) (*Recorder, error)

NewRecorder loads the deployment salt, generating it on first use.

func (*Recorder) Answer added in v0.4.0

func (r *Recorder) Answer(ctx context.Context, id int64) (Saved, error)

Answer reads one stored record back.

func (*Recorder) Count added in v0.4.0

func (r *Recorder) Count(ctx context.Context) (int, error)

Count returns how many answers have been recorded.

D12 gates graduation on a count of reviewed answers, so the denominator has to be readable.

func (*Recorder) DB added in v0.4.0

func (r *Recorder) DB() *store.DB

DB exposes the underlying database, for tests and for callers that share one store across components (R-ANS-5a keeps everything in a single database).

func (*Recorder) FeedbackFor added in v0.4.0

func (r *Recorder) FeedbackFor(ctx context.Context, answerID int64) (int, int, error)

FeedbackFor returns the helpful and not-helpful counts for an answer.

func (*Recorder) Forget added in v0.4.0

func (r *Recorder) Forget(ctx context.Context, userID chatplatform.ID) (int64, error)

Forget removes everything recorded for one person.

The published policy says deletion covers every store. The user hash is the only handle on their rows, which is why it is a stable pseudonym rather than a value regenerated per call.

Questions are anonymised rather than deleted: a question is not personal data once it is detached from who asked it, it was volunteered in a public channel, and deleting it would silently revise a documentation-gap count that nothing else can reconstruct.

func (*Recorder) Purge added in v0.4.0

func (r *Recorder) Purge(ctx context.Context, olderThan time.Duration) (int64, error)

Purge deletes questions older than the retention window.

A retention promise with no purge is a false statement rather than a missing feature, and the policy publishes this one. Topics are deliberately NOT deleted with their questions: the count is the product, and a subject that was asked about six months ago is still evidence of a gap even once the wording of the asking is gone.

func (*Recorder) Record added in v0.4.0

func (r *Recorder) Record(ctx context.Context, rec Record) (Saved, error)

Record stores one answer and returns what was stored.

func (*Recorder) RecordFeedback added in v0.4.0

func (r *Recorder) RecordFeedback(
	ctx context.Context, messageID, userID chatplatform.ID, helpful bool,
) error

RecordFeedback stores a verdict against the answer posted as messageID.

NOTHING CALLS THIS YET, and it cannot until chat-platform changes. Two pieces are missing upstream: Actor.ReplyInThread returns the thread's id rather than the id of the message it posted, and Reader delivers only messages — there is no inbound reaction event, so the bot can offer the affordance and never learn that anybody used it.

It is written and tested now because the semantics are the part worth getting right, and they are decided by D9 rather than by the platform: one verdict per person, replaced on a change of mind, and the bot's own reactions excluded.

Unknown messages are ignored rather than refused. People react to arbitrary messages constantly, and the overwhelming majority of reactions the bot sees are nothing to do with it — treating those as errors would make the normal case an error path.

func (*Recorder) Topics added in v0.4.0

func (r *Recorder) Topics(ctx context.Context, limit int) ([]Topic, error)

Topics returns the subjects people have asked about, most-asked first.

This is D14's product: a topic asked eleven times that declines every time is a documentation gap ranked by demand, which is better evidence than any individual decline and needs no volunteer action from anybody.

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 Saved added in v0.4.0

type Saved struct {
	ID int64
	// QuestionID links to the stored question, zero where there was nothing to
	// store or the question could not be recorded.
	QuestionID int64
	UserHash   string
	Outcome    answer.Outcome
	Posture    Posture
	Citations  int
	Posted     bool
	CreatedAt  time.Time
}

Saved is a stored answer record.

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.

type Topic added in v0.4.0

type Topic struct {
	ID    int64
	Label string
	// GuideSlug is the published guided topic page this corresponds to, empty
	// where no guide has been written. Empty on a topic asked often is the
	// backlog entry (spec 0008 §3.7).
	GuideSlug string
	// Asked is how many questions belong to this topic — the count D14 calls
	// the product of the answering path.
	Asked int
	First time.Time
	Last  time.Time
}

Topic is a subject people ask about.

Jump to

Keyboard shortcuts

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