Files
archie/modules/chat/api.go
T

448 lines
15 KiB
Go

package chat
import (
"context"
"errors"
"fmt"
"net/http"
"strconv"
"strings"
"time"
"unicode/utf8"
"github.com/danielgtaylor/huma/v2"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/internal/platform/httpapi"
"github.com/samcharles93/archie-core/internal/platform/hub"
"github.com/samcharles93/archie-core/modules/chat/internal/store"
"github.com/samcharles93/archie-core/modules/governance"
)
const (
sessionPage = 100
maxTextRunes = 32000
heartbeat = 15 * time.Second
)
// Register adds the chat API.
func (m *Module) Register(api huma.API) {
tags := []string{"Chat"}
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{
OperationID: "list-chat-sessions", Method: http.MethodGet, Path: "/api/chat/sessions",
Summary: "List conversations, most recently active first, with the model that answers", Tags: tags,
}, m.listSessions)
httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindChatSession), huma.Operation{
OperationID: "create-chat-session", Method: http.MethodPost, Path: "/api/chat/sessions",
Summary: "Start a conversation", Tags: tags, DefaultStatus: http.StatusCreated,
}, m.createSession)
httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindChatSession), huma.Operation{
OperationID: "rename-chat-session", Method: http.MethodPatch, Path: "/api/chat/sessions/{id}",
Summary: "Rename a conversation", Tags: tags,
}, m.renameSession)
httpapi.Register(api, httpapi.Authorized(governance.ActionDelete, governance.KindChatSession), huma.Operation{
OperationID: "delete-chat-session", Method: http.MethodDelete, Path: "/api/chat/sessions/{id}",
Summary: "Delete a conversation and its turns", Tags: tags, DefaultStatus: http.StatusNoContent,
}, m.deleteSession)
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{
OperationID: "list-chat-turns", Method: http.MethodGet, Path: "/api/chat/sessions/{id}/turns",
Summary: "List a conversation's turns with what each did", Tags: tags,
}, m.listTurns)
httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindChatSession), huma.Operation{
OperationID: "send-chat-turn", Method: http.MethodPost, Path: "/api/chat/sessions/{id}/turns",
Summary: "Send a message; it is stored, then answered after the turns before it", Tags: tags,
DefaultStatus: http.StatusAccepted,
}, m.sendTurn)
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{
OperationID: "get-chat-turn", Method: http.MethodGet, Path: "/api/chat/turns/{id}",
Summary: "Get one turn with what it did", Tags: tags,
}, m.getTurn)
httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindChatSession), huma.Operation{
OperationID: "cancel-chat-turn", Method: http.MethodPost, Path: "/api/chat/turns/{id}/cancel",
Summary: "Stop a turn that is queued or running", Tags: tags,
}, m.cancelTurn)
httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{
OperationID: "stream-chat-turn", Method: http.MethodGet, Path: "/api/chat/turns/{id}/events",
Summary: "Stream what a turn records, from a cursor, until it ends", Tags: tags,
Responses: map[string]*huma.Response{"200": {
Description: "Server-sent events, one data frame per recorded event: {\"seq\", \"type\", ...}. " +
"Types are reasoning, delta, tool, navigate, approval, action, done, error and cancelled; " +
"the stream ends after done, error or cancelled.",
Content: map[string]*huma.MediaType{"text/event-stream": {Schema: &huma.Schema{Type: huma.TypeString}}},
}},
}, m.streamTurn)
}
// Sessions is the conversation list with the model that answers turns.
type Sessions struct {
Sessions []Session `json:"sessions"`
ActiveModel string `json:"active_model"`
ModelError string `json:"model_error,omitzero"`
}
// caller is the identity a request acts as: the owner of the conversations
// it may see. A conversation of anyone else is not found.
func caller(ctx context.Context) (string, error) {
p, ok := governance.PrincipalFromContext(ctx)
if !ok || p.IdentityID == "" {
return "", huma.NewError(http.StatusUnauthorized, httpapi.ErrUnauthenticated.Error())
}
return string(p.IdentityID), nil
}
func (m *Module) listSessions(ctx context.Context, _ *struct{}) (*httpapi.Reply[Sessions], error) {
owner, err := caller(ctx)
if err != nil {
return nil, err
}
rows, err := m.store.Sessions(ctx, m.orgID, owner, sessionPage)
if err != nil {
m.log.ErrorContext(ctx, "list chat sessions", "error", err)
return nil, huma.NewError(http.StatusInternalServerError, "couldn't list conversations")
}
out := Sessions{Sessions: make([]Session, 0, len(rows))}
for _, r := range rows {
out.Sessions = append(out.Sessions, sessionOf(r))
}
if d, ok := m.uses(); ok {
if model, err := d.Settings.ChatModelForAlias(ctx, ""); err != nil {
out.ModelError = err.Error()
} else {
out.ActiveModel = model.Model
}
}
return httpapi.OK(out), nil
}
func (m *Module) createSession(ctx context.Context, _ *struct{}) (*httpapi.Reply[Session], error) {
owner, err := caller(ctx)
if err != nil {
return nil, err
}
s, err := m.store.CreateSession(ctx, m.orgID, owner, uuid.New())
if err != nil {
m.log.ErrorContext(ctx, "create chat session", "error", err)
return nil, huma.NewError(http.StatusInternalServerError, "couldn't start a conversation")
}
return httpapi.OK(sessionOf(s)), nil
}
type idInput struct {
ID string `path:"id" format:"uuid"`
}
type renameInput struct {
ID string `path:"id" format:"uuid"`
Body struct {
Title string `json:"title" maxLength:"120"`
}
}
func (m *Module) renameSession(ctx context.Context, in *renameInput) (*httpapi.Reply[Session], error) {
id, err := uuid.Parse(in.ID)
if err != nil {
return nil, huma.NewError(http.StatusBadRequest, "id is a conversation id")
}
owner, err := caller(ctx)
if err != nil {
return nil, err
}
if err := m.store.Rename(ctx, m.orgID, owner, id, strings.TrimSpace(in.Body.Title)); err != nil {
return nil, m.failed(ctx, err, "rename the conversation")
}
s, err := m.store.Session(ctx, m.orgID, owner, id)
if err != nil {
return nil, m.failed(ctx, err, "read the conversation")
}
return httpapi.OK(sessionOf(s)), nil
}
func (m *Module) deleteSession(ctx context.Context, in *idInput) (*struct{}, error) {
id, err := uuid.Parse(in.ID)
if err != nil {
return nil, huma.NewError(http.StatusBadRequest, "id is a conversation id")
}
owner, err := caller(ctx)
if err != nil {
return nil, err
}
turns, err := m.store.Turns(ctx, m.orgID, owner, id)
if err != nil {
return nil, m.failed(ctx, err, "read the conversation")
}
for _, t := range turns {
if !finished(t.State) {
return nil, huma.NewError(http.StatusConflict, "stop the conversation's turns before deleting it")
}
}
if err := m.store.DeleteSession(ctx, m.orgID, owner, id); err != nil {
return nil, m.failed(ctx, err, "delete the conversation")
}
return nil, nil
}
func (m *Module) listTurns(ctx context.Context, in *idInput) (*httpapi.Reply[[]Turn], error) {
id, err := uuid.Parse(in.ID)
if err != nil {
return nil, huma.NewError(http.StatusBadRequest, "id is a conversation id")
}
owner, err := caller(ctx)
if err != nil {
return nil, err
}
if _, err := m.store.Session(ctx, m.orgID, owner, id); err != nil {
return nil, m.failed(ctx, err, "read the conversation")
}
rows, err := m.store.Turns(ctx, m.orgID, owner, id)
if err != nil {
return nil, m.failed(ctx, err, "list the conversation's turns")
}
events, err := m.store.EventsOf(ctx, id, []string{kindTool, kindNavigate, kindApproval, kindAction})
if err != nil {
return nil, m.failed(ctx, err, "list what the turns did")
}
byTurn := map[uuid.UUID][]store.Event{}
for _, e := range events {
byTurn[e.TurnID] = append(byTurn[e.TurnID], e)
}
out := make([]Turn, 0, len(rows))
for _, r := range rows {
out = append(out, turnOf(r, byTurn[r.ID]))
}
return httpapi.OK(out), nil
}
func (m *Module) getTurn(ctx context.Context, in *idInput) (*httpapi.Reply[Turn], error) {
id, err := uuid.Parse(in.ID)
if err != nil {
return nil, huma.NewError(http.StatusBadRequest, "id is a turn id")
}
owner, err := caller(ctx)
if err != nil {
return nil, err
}
t, err := m.store.Turn(ctx, m.orgID, owner, id)
if err != nil {
return nil, m.failed(ctx, err, "read the turn")
}
events, err := m.store.Events(ctx, id, 0)
if err != nil {
return nil, m.failed(ctx, err, "read what the turn did")
}
return httpapi.OK(turnOf(t, events)), nil
}
// turnOf is a turn with what its recorded events say it did.
func turnOf(r store.Turn, events []store.Event) Turn {
t := Turn{
ID: r.ID, SessionID: r.SessionID, Seq: r.Seq, State: r.State, Text: r.Text, Page: r.Page, PageLabel: r.PageLabel,
Reply: r.Reply, Reasoning: r.Reasoning, Error: r.Error, CreatedAt: r.CreatedAt,
Tools: []ToolCall{}, Approvals: []Approval{}, Actions: []ActionDone{}, Navigate: []Navigation{},
}
if r.FinishedAt.Valid {
t.FinishedAt = &r.FinishedAt.Time
}
for _, e := range events {
var err error
switch e.Kind {
case kindTool:
var v ToolCall
if err = decodeData(e.Data, &v); err == nil {
t.Tools = append(t.Tools, v)
}
case kindNavigate:
var v Navigation
if err = decodeData(e.Data, &v); err == nil {
t.Navigate = append(t.Navigate, v)
}
case kindApproval:
var v Approval
if err = decodeData(e.Data, &v); err == nil {
t.Approvals = append(t.Approvals, v)
}
case kindAction:
var v ActionDone
if err = decodeData(e.Data, &v); err == nil {
t.Actions = append(t.Actions, v)
}
}
}
return t
}
type sendInput struct {
ID string `path:"id" format:"uuid"`
Body struct {
Text string `json:"text" minLength:"1"`
// Page is the dashboard path the operator asked from, and PageLabel
// the name the page goes by.
Page string `json:"page,omitempty" maxLength:"500"`
PageLabel string `json:"page_label,omitempty" maxLength:"200"`
}
}
func (m *Module) sendTurn(ctx context.Context, in *sendInput) (*httpapi.Reply[Turn], error) {
id, err := uuid.Parse(in.ID)
if err != nil {
return nil, huma.NewError(http.StatusBadRequest, "id is a conversation id")
}
owner, err := caller(ctx)
if err != nil {
return nil, err
}
text := strings.TrimSpace(in.Body.Text)
switch {
case text == "":
return nil, huma.NewError(http.StatusBadRequest, "a message needs text")
case utf8.RuneCountInString(text) > maxTextRunes:
return nil, huma.NewError(http.StatusBadRequest, fmt.Sprintf("a message is at most %d characters", maxTextRunes))
}
t, err := m.store.AddTurn(ctx, m.orgID, owner, store.Turn{
ID: uuid.New(), SessionID: id, Text: text, Page: in.Body.Page, PageLabel: in.Body.PageLabel,
})
if err != nil {
return nil, m.failed(ctx, err, "send the message")
}
m.poke()
return httpapi.OK(turnOf(t, nil)), nil
}
func (m *Module) cancelTurn(ctx context.Context, in *idInput) (*httpapi.Reply[Turn], error) {
id, err := uuid.Parse(in.ID)
if err != nil {
return nil, huma.NewError(http.StatusBadRequest, "id is a turn id")
}
owner, err := caller(ctx)
if err != nil {
return nil, err
}
wasQueued, err := m.store.RequestCancel(ctx, m.orgID, owner, id)
if err != nil {
return nil, m.failed(ctx, err, "stop the turn")
}
if wasQueued {
m.record(ctx, id, kindCancelled, map[string]any{"text": ""})
}
m.mu.Lock()
stop := m.running[id]
m.mu.Unlock()
if stop != nil {
stop()
}
t, err := m.store.Turn(ctx, m.orgID, owner, id)
if err != nil {
return nil, m.failed(ctx, err, "read the turn")
}
return httpapi.OK(turnOf(t, nil)), nil
}
type streamInput struct {
ID string `path:"id" format:"uuid"`
After string `query:"after" doc:"Only events after this seq; every event by default"`
}
// streamTurn replays a turn's recorded events after the cursor, then follows
// new ones until the turn ends. A reader that reconnects passes its last seq
// and misses nothing.
func (m *Module) streamTurn(ctx context.Context, in *streamInput) (*huma.StreamResponse, error) {
id, err := uuid.Parse(in.ID)
if err != nil {
return nil, huma.NewError(http.StatusBadRequest, "id is a turn id")
}
var after int64
if in.After != "" {
if after, err = strconv.ParseInt(in.After, 10, 64); err != nil || after < 0 {
return nil, huma.NewError(http.StatusBadRequest, "after is an event seq")
}
}
owner, err := caller(ctx)
if err != nil {
return nil, err
}
if _, err := m.store.Turn(ctx, m.orgID, owner, id); err != nil {
return nil, m.failed(ctx, err, "read the turn")
}
return &huma.StreamResponse{Body: func(hc huma.Context) { m.serveEvents(hc, id, after) }}, nil //nolint:contextcheck // a stream takes its context from the response it writes, which ends with the request
}
// serveEvents streams a turn's events to one reader.
func (m *Module) serveEvents(hc huma.Context, id uuid.UUID, after int64) {
ctx := hc.Context()
w := hc.BodyWriter()
flusher, ok := w.(http.Flusher)
if !ok {
hc.SetStatus(http.StatusInternalServerError)
return
}
notes, stop := m.hub.Subscribe(topic(id))
defer stop()
hc.SetHeader("Content-Type", "text/event-stream")
hc.SetHeader("Cache-Control", "no-store")
hc.SetStatus(http.StatusOK)
flusher.Flush()
m.follow(ctx, id, after, notes, func(frame string) bool {
if _, err := fmt.Fprint(w, frame); err != nil {
return false
}
flusher.Flush()
return true
})
}
// follow writes a turn's events after the cursor until the turn ends, the
// reader leaves or a write fails.
func (m *Module) follow(ctx context.Context, id uuid.UUID, after int64, notes <-chan hub.Note, write func(string) bool) {
tick := time.NewTicker(heartbeat)
defer tick.Stop()
for {
events, err := m.store.Events(ctx, id, after)
if err != nil {
if ctx.Err() == nil {
m.log.ErrorContext(ctx, "read chat events", "turn", id, "error", err)
}
return
}
for _, e := range events {
after = e.Seq
if !write(frame(e)) {
return
}
if e.Kind == kindDone || e.Kind == kindError || e.Kind == kindCancelled {
return
}
}
select {
case <-ctx.Done():
return
case _, ok := <-notes:
if !ok {
return
}
case <-tick.C:
if !write(": keepalive\n\n") {
return
}
}
}
}
// frame is one event as a server-sent event: its data with its seq and type.
func frame(e store.Event) string {
data := strings.TrimSpace(string(e.Data))
head := fmt.Sprintf(`{"seq":%d,"type":%q`, e.Seq, e.Kind)
if data != "{}" && strings.HasPrefix(data, "{") {
head += "," + data[1:]
} else {
head += "}"
}
return "id: " + strconv.FormatInt(e.Seq, 10) + "\ndata: " + head + "\n\n"
}
func (m *Module) failed(ctx context.Context, err error, what string) error {
if errors.Is(err, store.ErrNotFound) {
return huma.NewError(http.StatusNotFound, "not found")
}
m.log.ErrorContext(ctx, "chat: "+what, "error", err)
return huma.NewError(http.StatusInternalServerError, "couldn't "+what)
}