package memory import ( "context" "errors" "net/http" "strings" "github.com/danielgtaylor/huma/v2" "github.com/google/uuid" "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/modules/governance" ) // Register adds the memory API. The routes a person uses to read and correct // their own notes are scoped to the signed-in caller; the ones that publish, // revoke or roll back a shared note need an instance administrator. func (m *Module) Register(api huma.API) { tags := []string{"Memory"} httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindNote), huma.Operation{ OperationID: "list-memory-notes", Method: http.MethodGet, Path: "/api/memory/notes", Summary: "List the notes you may read", Tags: tags, }, m.notesOfCaller) httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindNote), huma.Operation{ OperationID: "remember-memory-note", Method: http.MethodPost, Path: "/api/memory/notes", Summary: "Remember a note for yourself", Tags: tags, }, m.rememberNote) httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindNote), huma.Operation{ OperationID: "correct-memory-note", Method: http.MethodPatch, Path: "/api/memory/notes/{id}", Summary: "Correct one of your notes", Tags: tags, }, m.correctNote) httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindNote), huma.Operation{ OperationID: "disable-memory-note", Method: http.MethodPost, Path: "/api/memory/notes/{id}/disabled", Summary: "Stop one of your notes being read, or resume it", Tags: tags, }, m.disableNote) httpapi.Register(api, httpapi.Authorized(governance.ActionDelete, governance.KindNote), huma.Operation{ OperationID: "forget-memory-note", Method: http.MethodDelete, Path: "/api/memory/notes/{id}", Summary: "Forget one of your notes", Tags: tags, }, m.forgetNote) httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindNote), huma.Operation{ OperationID: "propose-shared-note", Method: http.MethodPost, Path: "/api/memory/proposals", Summary: "Propose a note for the whole organisation", Tags: tags, }, m.proposeNote) httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindMemory), huma.Operation{ OperationID: "list-shared-notes", Method: http.MethodGet, Path: "/api/memory/shared", Summary: "List the notes published to the organisation", Tags: tags, }, m.sharedNotes) httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionCreate, governance.KindMemory), huma.Operation{ OperationID: "publish-shared-note", Method: http.MethodPost, Path: "/api/memory/shared", Summary: "Publish a note to the whole organisation", Tags: tags, }, m.publishNote) httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindMemory), huma.Operation{ OperationID: "list-note-proposals", Method: http.MethodGet, Path: "/api/memory/proposals", Summary: "List notes waiting to be published", Tags: tags, }, m.pendingNotes) httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindMemory), huma.Operation{ OperationID: "approve-note-proposal", Method: http.MethodPost, Path: "/api/memory/proposals/{id}/publish", Summary: "Publish a proposed note", Tags: tags, }, m.approveNote) httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionDelete, governance.KindMemory), huma.Operation{ OperationID: "revoke-shared-note", Method: http.MethodDelete, Path: "/api/memory/shared/{id}", Summary: "Revoke a shared note, published or proposed", Tags: tags, }, m.revokeNote) httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionRead, governance.KindMemory), huma.Operation{ OperationID: "list-note-versions", Method: http.MethodGet, Path: "/api/memory/shared/{id}/versions", Summary: "List the published versions of a shared note", Tags: tags, }, m.noteVersions) httpapi.Register(api, httpapi.AdminAuthorized(governance.ActionUpdate, governance.KindMemory), huma.Operation{ OperationID: "roll-back-shared-note", Method: http.MethodPost, Path: "/api/memory/shared/{id}/rollback", Summary: "Publish an earlier version of a shared note again", Tags: tags, }, m.rollbackNote) } // notes is the response body listing notes. type notes struct { Notes []Note `json:"notes"` } // idInput names one note. type idInput struct { ID string `path:"id" format:"uuid" doc:"The note's id"` } type notesInput struct { Class string `query:"class" enum:"working_context,episodic_history,enterprise_retrieval,durable_fact" doc:"The memory class, durable facts by default"` } type textInput struct { Body struct { Text string `json:"text" doc:"The note itself. A credential-shaped value is redacted, and a credential or a security override is refused."` } } type correctInput struct { ID string `path:"id" format:"uuid"` Body struct { Text string `json:"text" doc:"The corrected note"` } } type disabledInput struct { ID string `path:"id" format:"uuid"` Body struct { Disabled bool `json:"disabled" doc:"Whether the note stops being read"` } } type rollbackInput struct { ID string `path:"id" format:"uuid"` Body struct { Version int `json:"version" doc:"The published version to publish again"` } } // caller is the signed-in person, whose notes the request is about. 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 } // classOf reads the class a request is about, defaulting to the durable facts a // conversation remembers. func classOf(class string) (Class, error) { if strings.TrimSpace(class) == "" { return ClassDurableFact, nil } c := Class(class) if err := c.Validate(); err != nil { return "", huma.NewError(http.StatusBadRequest, "class is one of the memory classes") } return c, nil } func (m *Module) notesOfCaller(ctx context.Context, in *notesInput) (*httpapi.Reply[notes], error) { owner, err := caller(ctx) if err != nil { return nil, err } class, err := classOf(in.Class) if err != nil { return nil, err } mine, err := m.Mine(ctx, owner, class) if err != nil { m.log.ErrorContext(ctx, "list notes", "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't list your notes") } shared, err := m.Shared(ctx, class) if err != nil { m.log.ErrorContext(ctx, "list shared notes", "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't list the shared notes") } return httpapi.OK(notes{Notes: append(mine, shared...)}), nil } // rememberNote stores a note in the caller's own scope. A conversation's // memory_save tool writes the same way, as the person the turn acts for. func (m *Module) rememberNote(ctx context.Context, in *textInput) (*httpapi.Reply[Note], error) { owner, err := caller(ctx) if err != nil { return nil, err } note, err := m.Remember(ctx, owner, in.Body.Text) switch { case errors.Is(err, ErrInvalidNote): return nil, huma.NewError(http.StatusBadRequest, err.Error()) case err != nil: m.log.ErrorContext(ctx, "remember note", "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't remember the note") } return httpapi.OK(note), nil } func (m *Module) correctNote(ctx context.Context, in *correctInput) (*httpapi.Reply[Note], error) { owner, err := caller(ctx) if err != nil { return nil, err } id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a note id") } note, ok, err := m.Correct(ctx, owner, id, in.Body.Text) switch { case errors.Is(err, ErrInvalidNote): return nil, huma.NewError(http.StatusBadRequest, err.Error()) case err != nil: m.log.ErrorContext(ctx, "correct note", "note", id, "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't correct the note") case !ok: return nil, huma.NewError(http.StatusNotFound, "no note of yours has that id") } return httpapi.OK(note), nil } func (m *Module) disableNote(ctx context.Context, in *disabledInput) (*struct{}, error) { owner, err := caller(ctx) if err != nil { return nil, err } id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a note id") } ok, err := m.Disable(ctx, owner, id, in.Body.Disabled) if err != nil { m.log.ErrorContext(ctx, "disable note", "note", id, "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't change the note") } if !ok { return nil, huma.NewError(http.StatusNotFound, "no note of yours has that id") } return nil, nil } func (m *Module) forgetNote(ctx context.Context, in *idInput) (*struct{}, error) { owner, err := caller(ctx) if err != nil { return nil, err } id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a note id") } ok, err := m.Forget(ctx, owner, id) switch { case errors.Is(err, ErrRecordIncomplete): // The note is gone; only its record is pending. Saying so exactly is the // point: the caller must not be told the deletion is fully durable, and // must not be told it failed either. m.log.ErrorContext(ctx, "record a deletion", "note", id, "error", err) return nil, huma.NewError(http.StatusServiceUnavailable, "the note was deleted and the record of its deletion is pending; it is retried until it is written") case err != nil: m.log.ErrorContext(ctx, "forget note", "note", id, "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't forget the note") case !ok: return nil, huma.NewError(http.StatusNotFound, "no note of yours has that id") } return nil, nil } func (m *Module) proposeNote(ctx context.Context, in *textInput) (*httpapi.Reply[Note], error) { owner, err := caller(ctx) if err != nil { return nil, err } note, err := m.Propose(ctx, owner, in.Body.Text) if errors.Is(err, ErrInvalidNote) { return nil, huma.NewError(http.StatusBadRequest, err.Error()) } if err != nil { m.log.ErrorContext(ctx, "propose shared note", "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't record the proposal") } return httpapi.OK(note), nil } func (m *Module) sharedNotes(ctx context.Context, in *notesInput) (*httpapi.Reply[notes], error) { class, err := classOf(in.Class) if err != nil { return nil, err } rows, err := m.Shared(ctx, class) if err != nil { m.log.ErrorContext(ctx, "list shared notes", "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't list the shared notes") } return httpapi.OK(notes{Notes: rows}), nil } func (m *Module) pendingNotes(ctx context.Context, _ *struct{}) (*httpapi.Reply[notes], error) { rows, err := m.Pending(ctx) if err != nil { m.log.ErrorContext(ctx, "list note proposals", "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't list the proposals") } return httpapi.OK(notes{Notes: rows}), nil } func (m *Module) publishNote(ctx context.Context, in *textInput) (*httpapi.Reply[Note], error) { publisher, err := caller(ctx) if err != nil { return nil, err } note, err := m.Publish(ctx, publisher, "", in.Body.Text) if errors.Is(err, ErrInvalidNote) { return nil, huma.NewError(http.StatusBadRequest, err.Error()) } if err != nil { m.log.ErrorContext(ctx, "publish shared note", "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't publish the note") } return httpapi.OK(note), nil } func (m *Module) approveNote(ctx context.Context, in *idInput) (*httpapi.Reply[Note], error) { publisher, err := caller(ctx) if err != nil { return nil, err } id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a note id") } note, ok, err := m.Approve(ctx, publisher, id) if err != nil { m.log.ErrorContext(ctx, "publish proposed note", "note", id, "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't publish the note") } if !ok { return nil, huma.NewError(http.StatusNotFound, "no proposal has that id") } return httpapi.OK(note), nil } func (m *Module) revokeNote(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 note id") } ok, err := m.Revoke(ctx, id) if errors.Is(err, ErrRecordIncomplete) { m.log.ErrorContext(ctx, "record a deletion", "note", id, "error", err) return nil, huma.NewError(http.StatusServiceUnavailable, "the note was deleted and the record of its deletion is pending; it is retried until it is written") } if err != nil { m.log.ErrorContext(ctx, "revoke shared note", "note", id, "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't revoke the note") } if !ok { return nil, huma.NewError(http.StatusNotFound, "no shared note has that id") } return nil, nil } type versions struct { Versions []Version `json:"versions"` } func (m *Module) noteVersions(ctx context.Context, in *idInput) (*httpapi.Reply[versions], error) { id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a note id") } rows, err := m.Versions(ctx, id) if err != nil { m.log.ErrorContext(ctx, "list note versions", "note", id, "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't list the note's versions") } return httpapi.OK(versions{Versions: rows}), nil } func (m *Module) rollbackNote(ctx context.Context, in *rollbackInput) (*httpapi.Reply[Note], error) { publisher, err := caller(ctx) if err != nil { return nil, err } id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a note id") } note, ok, err := m.Rollback(ctx, publisher, id, in.Body.Version) if err != nil { m.log.ErrorContext(ctx, "roll back shared note", "note", id, "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't roll the note back") } if !ok { return nil, huma.NewError(http.StatusNotFound, "the note has no such published version") } return httpapi.OK(note), nil }