Jay Brown
250 lines
8.8 KiB
Go
250 lines
8.8 KiB
Go
package bot
|
||
|
||
import (
|
||
"encoding/json"
|
||
"time"
|
||
|
||
"github.com/google/uuid"
|
||
)
|
||
|
||
// Session is the service-layer representation of a chatbot session.
|
||
// Handlers translate this into BotSessionResponse for the wire. Fields
|
||
// match plan §3 / §4: lastTurn = last_terminal_ordinal (the highest
|
||
// ordinal whose status is not in_flight), never the in-flight ordinal.
|
||
type Session struct {
|
||
ID uuid.UUID
|
||
ClientID string
|
||
CreatedBy string
|
||
Title string
|
||
State json.RawMessage
|
||
LastTurn int32
|
||
CreatedAt time.Time
|
||
UpdatedAt time.Time
|
||
Scope SessionScope
|
||
RecentTurns []TurnPreview
|
||
IsDeleted bool
|
||
}
|
||
|
||
// SessionScope is the persisted (documents, folders) tuple. Returned as
|
||
// id arrays per plan §3 — folder expansion to documents lives in the
|
||
// M3 FastAPI payload assembly path, not here.
|
||
type SessionScope struct {
|
||
DocumentIDs []uuid.UUID
|
||
FolderIDs []uuid.UUID
|
||
}
|
||
|
||
// TurnPreview is a single recent-turn row surfaced in the session-list
|
||
// response. M2 returns the columns the UI needs for a preview card.
|
||
type TurnPreview struct {
|
||
Ordinal int32
|
||
Prompt string
|
||
Completion *string
|
||
Status string
|
||
CreatedAt time.Time
|
||
}
|
||
|
||
// ListSessionsInput drives ListSessionsForOwner / ListSessionsForSuperAdmin.
|
||
// Limit and Offset are validated up-front by the handler; the service
|
||
// re-validates as defense in depth so non-HTTP callers cannot bypass
|
||
// the [1, 200] / >= 0 bounds plan §3 mandates.
|
||
type ListSessionsInput struct {
|
||
Limit int
|
||
Offset int
|
||
}
|
||
|
||
// PatchScopeInput carries the body of PATCH /scope. The service
|
||
// deduplicates each array, rejects an id that appears in both add and
|
||
// remove sets, and rejects cross-client ids.
|
||
type PatchScopeInput struct {
|
||
AddDocuments []uuid.UUID
|
||
RemoveDocuments []uuid.UUID
|
||
AddFolders []uuid.UUID
|
||
RemoveFolders []uuid.UUID
|
||
}
|
||
|
||
// ---------- M3: FastAPI agent service wire types ----------
|
||
//
|
||
// Field shapes are pinned by plans/chatbot.stuff/openapi.chatbot.swagger.json
|
||
// (the "Aaria Agent Service" v0.1.0 contract). Plan §7 defines the
|
||
// request/response mapping; these structs serialize 1:1 to the swagger
|
||
// schema with snake_case JSON tags.
|
||
|
||
// ChatRequest is the body sent to POST /agent/chat. Plan §7 mapping
|
||
// table: request_id is "{sessionId}:{ordinal}" stable across retries;
|
||
// user_id is the Cognito sub treated as opaque telemetry; session_id is
|
||
// bot_sessions.id as a string; conversation_history is the last N
|
||
// completed turns × 2 messages; session_state is bot_sessions.state from
|
||
// tx1 (nil when the session has no state); scope is the assembled
|
||
// document/folder set.
|
||
type ChatRequest struct {
|
||
RequestID string `json:"request_id"`
|
||
UserID string `json:"user_id"`
|
||
SessionID string `json:"session_id"`
|
||
Message string `json:"message"`
|
||
ConversationHistory []ConversationMessage `json:"conversation_history"`
|
||
SessionState *SessionState `json:"session_state,omitempty"`
|
||
Scope ChatScope `json:"scope"`
|
||
}
|
||
|
||
// ChatResponse is the body returned by POST /agent/chat. Plan §7
|
||
// mandates that updated_session_state == null preserves the prior state
|
||
// and an explicit {} overwrites it; the *json.RawMessage type is the
|
||
// standard Go idiom for distinguishing those two cases at unmarshal.
|
||
type ChatResponse struct {
|
||
RequestID string `json:"request_id"`
|
||
Status string `json:"status"`
|
||
Answer *Answer `json:"answer,omitempty"`
|
||
UpdatedSessionState *json.RawMessage `json:"updated_session_state,omitempty"`
|
||
Metadata *Metadata `json:"metadata,omitempty"`
|
||
Error *ErrorPayload `json:"error,omitempty"`
|
||
}
|
||
|
||
// ChatScope is the assembled document/folder payload sent to FastAPI.
|
||
// Both fields are emitted as non-null arrays (the swagger marks them
|
||
// required) — empty input produces "[]", not "null".
|
||
type ChatScope struct {
|
||
DocumentIDs []string `json:"document_ids"`
|
||
FolderIDs []string `json:"folder_ids"`
|
||
}
|
||
|
||
// ConversationMessage is one entry in conversation_history. Plan §7:
|
||
// each completed turn produces a (user, assistant) pair with the turn's
|
||
// created_at as the timestamp.
|
||
type ConversationMessage struct {
|
||
Role string `json:"role"`
|
||
Content string `json:"content"`
|
||
Timestamp time.Time `json:"timestamp"`
|
||
}
|
||
|
||
// Answer is the agent's response payload. v1 plan §3 mandates that
|
||
// citations live in answer.text markdown; structured_data and
|
||
// follow_up_suggestions are response-only fields (logged or surfaced,
|
||
// not persisted).
|
||
type Answer struct {
|
||
Text string `json:"text"`
|
||
ResultType string `json:"result_type"`
|
||
StructuredData json.RawMessage `json:"structured_data,omitempty"`
|
||
FollowUpSuggestions []string `json:"follow_up_suggestions,omitempty"`
|
||
Confidence float64 `json:"confidence"`
|
||
}
|
||
|
||
// Metadata is the per-call telemetry from the agent service. The
|
||
// authoritative swagger declares Agents as a MAP keyed by agent name
|
||
// (NOT an array). SummarizeMetadata sums tokens by iterating map values.
|
||
type Metadata struct {
|
||
TotalLatencyMs int `json:"total_latency_ms"`
|
||
RetryCount int `json:"retry_count"`
|
||
Agents map[string]AgentTelemetry `json:"agents"`
|
||
}
|
||
|
||
// AgentTelemetry is one entry in the Metadata.Agents map. Passed is a
|
||
// pointer so the field can round-trip null → unset as the swagger allows.
|
||
type AgentTelemetry struct {
|
||
LatencyMs int `json:"latency_ms"`
|
||
InputTokens int `json:"input_tokens"`
|
||
OutputTokens int `json:"output_tokens"`
|
||
Passed *bool `json:"passed,omitempty"`
|
||
}
|
||
|
||
// ErrorPayload is the error-shape returned by FastAPI for a 200 response
|
||
// with status:"error" or carried alongside the error sentinel surfaced
|
||
// by the client when the upstream fails the application path.
|
||
type ErrorPayload struct {
|
||
Code string `json:"code"`
|
||
Message string `json:"message"`
|
||
}
|
||
|
||
// HealthResponse is the body returned by GET /health. Plan §7 mandates
|
||
// status == "ok" plus non-empty service and version.
|
||
type HealthResponse struct {
|
||
Status string `json:"status"`
|
||
Service string `json:"service"`
|
||
Version string `json:"version"`
|
||
}
|
||
|
||
// SessionState is the agent-side session-state object. The swagger
|
||
// defines it as an open object with no enumerated keys; we use a
|
||
// json.RawMessage alias so the client passes the bytes through
|
||
// untouched and the M4 tx2 path can apply StripCachedResults /
|
||
// SessionStateOversize gates without re-decoding. M4 may refine if
|
||
// structured access becomes useful.
|
||
type SessionState = json.RawMessage
|
||
|
||
// ChatCallResult is what FastAPIClient.Chat returns on success. The
|
||
// service layer reads SentAt/ReceivedAt for the wall-clock fallback when
|
||
// metadata is absent (plan §7 mapping table) and AttemptCount when
|
||
// persisting bot_turns.error per plan §6.
|
||
type ChatCallResult struct {
|
||
Response *ChatResponse
|
||
SentAt time.Time
|
||
ReceivedAt time.Time
|
||
AttemptCount int
|
||
}
|
||
|
||
// AttemptCounter is implemented by every error returned by
|
||
// FastAPIClient.Chat so the service layer can record the attempt count
|
||
// in bot_turns.error without unwrapping driver-specific types. Plan §7
|
||
// mandates the error path expose AttemptCount alongside the result path.
|
||
type AttemptCounter interface {
|
||
error
|
||
AttemptCount() int
|
||
}
|
||
|
||
// ---------- M4: AddTurn types ----------
|
||
|
||
// AddTurnInput drives Service.AddTurn. Caller specifies Ordinal: the
|
||
// handler computes it from session state via prompt-match semantics
|
||
// before calling the service; the concurrency test passes Ordinal
|
||
// directly. Plan §6 algorithm is by-ordinal.
|
||
type AddTurnInput struct {
|
||
SessionID uuid.UUID
|
||
ClientID string
|
||
Actor string
|
||
Ordinal int
|
||
Prompt string
|
||
}
|
||
|
||
// AddTurnResult is the per-call outcome the handler converts into
|
||
// BotTurnResponse. Status is one of the bot_turns.status enum values.
|
||
// Error is the persisted error JSON when status in (errored, abandoned,
|
||
// session_deleted), nil otherwise.
|
||
type AddTurnResult struct {
|
||
Ordinal int32
|
||
Status string
|
||
Completion *string
|
||
LatencyMs int
|
||
TokensIn int
|
||
TokensOut int
|
||
Error []byte
|
||
AttemptCount int
|
||
CreatedAt time.Time
|
||
}
|
||
|
||
// CompleteTurnInput is the argument shape for Service.CompleteBotTurnWithAttempt.
|
||
// Plan §11 stale-tx2 test exercises this directly so a stale callback
|
||
// (whose AttemptID does not match the persisted row) returns
|
||
// ErrTurnSuperseded.
|
||
type CompleteTurnInput struct {
|
||
SessionID uuid.UUID
|
||
Ordinal int
|
||
AttemptID uuid.UUID
|
||
Completion string
|
||
LatencyMs int
|
||
TokensIn int
|
||
TokensOut int
|
||
}
|
||
|
||
// Turn is the service-layer representation of one bot_turns row. The
|
||
// handler converts this into BotTurnResponse for the wire.
|
||
type Turn struct {
|
||
Ordinal int32
|
||
Prompt string
|
||
Completion *string
|
||
Status string
|
||
LatencyMs *int32
|
||
TokensIn *int32
|
||
TokensOut *int32
|
||
Error []byte
|
||
CreatedAt time.Time
|
||
}
|