drwily/petal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 3: LLM grammar checkpoint

Browse Source 
Backend (internal/llm): backend-agnostic LLMClient interface + factory
with vLLM (OpenAI-compat) and Ollama (native) clients, each Complete +
Stream. prompts.go holds the checkpoint and Ask Petal templates;
checkpoint.go salvages JSON from model output (brace-matched), enforces a
per-doc 30s RateLimiter, and truncates the doc to a latency cap.

internal/suggestions: POST /api/docs/:id/check runs a checkpoint and
replaces the doc's pending suggestions in one tx (accepted/rejected kept
as history); GET /api/docs/:id/suggestions lists pending;
POST /api/suggestions/:id/{accept,dismiss} resolves one. Throttled checks
return the current set rather than erroring.

Frontend: useCheckpoint (4s debounce, loads existing on open, stale-guard
tokens); SuggestionHighlight renders ProseMirror decorations re-anchored
by the `original` string on every doc change (not stored marks), with
precise textblock-offset→PM-position mapping; SuggestionCard shows the
type tag + diff + explanation and applies the replacement in-editor on
accept; breathing rose checkpoint dot in the StatusBar; fade-float +
breathe animations.

Tests: llm parse/rate-limit/truncate; suggestions full flow + rate-limit
over httptest with a stub client. Smoke-tested end-to-end against a fake
vLLM endpoint (anchoring verified) and the LLM-unreachable 502 path.

Claude-Session: https://claude.ai/code/session_016Yr6jELuRc7hyzYLccQKZd
This commit is contained in:
prosolis
2026-06-25 20:45:30 -07:00
parent 5e00cdce88
commit a4069d5755
18 changed files with 1640 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

246
internal/suggestions/handlers.go Normal file
View File

@@ -0,0 +1,246 @@
// Package suggestions implements the grammar-checkpoint endpoint and the
// accept/dismiss surface for LLM-proposed edits. Checkpoints run a single LLM
// pass over a document and persist the resulting pending suggestions; the
// frontend re-anchors each one by its `original` string at render time, so the
// stored positions are advisory only (spec Note #6).
package suggestions
import (
"database/sql"
"encoding/json"
"errors"
"net/http"
"strings"
"github.com/go-chi/chi/v5"
"gitea.parodia.dev/drwily/petal/internal/db"
"gitea.parodia.dev/drwily/petal/internal/llm"
)
// Handler holds the dependencies for the checkpoint + suggestion routes.
type Handler struct {
DB *db.DB
Client llm.LLMClient
Limit *llm.RateLimiter
}
// New constructs a Handler with a per-document checkpoint rate limiter.
func New(database *db.DB, client llm.LLMClient) *Handler {
return &Handler{
DB: database,
Client: client,
Limit: llm.NewRateLimiter(llm.CheckpointInterval),
}
}
// RegisterDocRoutes adds the document-scoped routes (check + list) onto the
// existing /api/docs router so they share its base path.
func (h *Handler) RegisterDocRoutes(r chi.Router) {
r.Post("/{id}/check", h.check)
r.Get("/{id}/suggestions", h.listForDoc)
}
// Routes returns the router mounted at /api/suggestions for per-suggestion
// actions.
func (h *Handler) Routes() chi.Router {
r := chi.NewRouter()
r.Post("/{id}/accept", h.accept)
r.Post("/{id}/dismiss", h.dismiss)
return r
}
// check runs a grammar checkpoint over the document and returns the fresh
// pending suggestions. It is rate-limited per document (429 when too soon).
func (h *Handler) check(w http.ResponseWriter, r *http.Request) {
docID := chi.URLParam(r, "id")
var contentText string
err := h.DB.QueryRow(
`SELECT content_text FROM documents WHERE id = ? AND user_id = ?`,
docID, db.LocalUserID,
).Scan(&contentText)
if errors.Is(err, sql.ErrNoRows) {
errorJSON(w, http.StatusNotFound, "document not found")
return
}
if err != nil {
serverError(w, err)
return
}
// Nothing to check on an empty document — skip the LLM round-trip.
if strings.TrimSpace(contentText) == "" {
writeJSON(w, http.StatusOK, []db.Suggestion{})
return
}
if ok, _ := h.Limit.Allow(docID); !ok {
// Throttled: return the existing pending set unchanged rather than an
// error, so the frontend keeps showing current suggestions.
existing, err := h.fetchPending(docID)
if err != nil {
serverError(w, err)
return
}
writeJSON(w, http.StatusOK, existing)
return
}
raw, err := llm.RunCheckpoint(r.Context(), h.Client, contentText)
if err != nil {
errorJSON(w, http.StatusBadGateway, "checkpoint failed: "+err.Error())
return
}
saved, err := h.replacePending(docID, contentText, raw)
if err != nil {
serverError(w, err)
return
}
writeJSON(w, http.StatusOK, saved)
}
// replacePending swaps a document's pending suggestions for a fresh batch in one
// transaction. Accepted/rejected suggestions are left untouched (history).
func (h *Handler) replacePending(docID, contentText string, raw []llm.RawSuggestion) ([]db.Suggestion, error) {
tx, err := h.DB.Begin()
if err != nil {
return nil, err
}
defer tx.Rollback()
if _, err := tx.Exec(
`DELETE FROM suggestions WHERE doc_id = ? AND status = ?`,
docID, db.SuggestionStatusPending,
); err != nil {
return nil, err
}
out := []db.Suggestion{}
for _, s := range raw {
typ := normalizeType(s.Type)
from, to := locate(contentText, s.Original)
var saved db.Suggestion
err := tx.QueryRow(
`INSERT INTO suggestions (doc_id, from_pos, to_pos, original, replacement, explanation, type)
VALUES (?, ?, ?, ?, ?, ?, ?)
RETURNING id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at`,
docID, from, to, s.Original, s.Replacement, s.Explanation, typ,
).Scan(
&saved.ID, &saved.DocID, &saved.FromPos, &saved.ToPos, &saved.Original,
&saved.Replacement, &saved.Explanation, &saved.Type, &saved.Status, &saved.CreatedAt,
)
if err != nil {
return nil, err
}
out = append(out, saved)
}
if err := tx.Commit(); err != nil {
return nil, err
}
return out, nil
}
// listForDoc returns the document's current pending suggestions (used when the
// editor loads a document, before any new checkpoint fires).
func (h *Handler) listForDoc(w http.ResponseWriter, r *http.Request) {
out, err := h.fetchPending(chi.URLParam(r, "id"))
if err != nil {
serverError(w, err)
return
}
writeJSON(w, http.StatusOK, out)
}
func (h *Handler) fetchPending(docID string) ([]db.Suggestion, error) {
rows, err := h.DB.Query(
`SELECT id, doc_id, from_pos, to_pos, original, replacement, explanation, type, status, created_at
FROM suggestions
WHERE doc_id = ? AND status = ?
ORDER BY from_pos ASC, created_at ASC`,
docID, db.SuggestionStatusPending,
)
if err != nil {
return nil, err
}
defer rows.Close()
out := []db.Suggestion{}
for rows.Next() {
var s db.Suggestion
if err := rows.Scan(
&s.ID, &s.DocID, &s.FromPos, &s.ToPos, &s.Original, &s.Replacement,
&s.Explanation, &s.Type, &s.Status, &s.CreatedAt,
); err != nil {
return nil, err
}
out = append(out, s)
}
return out, rows.Err()
}
// accept marks a suggestion accepted (the client applies the replacement text).
func (h *Handler) accept(w http.ResponseWriter, r *http.Request) {
h.setStatus(w, r, db.SuggestionStatusAccepted)
}
// dismiss marks a suggestion rejected.
func (h *Handler) dismiss(w http.ResponseWriter, r *http.Request) {
h.setStatus(w, r, db.SuggestionStatusRejected)
}
func (h *Handler) setStatus(w http.ResponseWriter, r *http.Request, status string) {
res, err := h.DB.Exec(
`UPDATE suggestions SET status = ? WHERE id = ? AND status = ?`,
status, chi.URLParam(r, "id"), db.SuggestionStatusPending,
)
if err != nil {
serverError(w, err)
return
}
if n, _ := res.RowsAffected(); n == 0 {
errorJSON(w, http.StatusNotFound, "pending suggestion not found")
return
}
w.WriteHeader(http.StatusNoContent)
}
// locate finds the plaintext offsets of original within contentText. Returns
// (-1, -1) when not found; the frontend anchors by string regardless, so a miss
// here is non-fatal.
func locate(contentText, original string) (int, int) {
idx := strings.Index(contentText, original)
if idx < 0 {
return -1, -1
}
return idx, idx + len(original)
}
// normalizeType maps the model's type string onto a valid suggestion type,
// defaulting unknown values to grammar so a stray label never trips the CHECK.
func normalizeType(t string) string {
switch strings.ToLower(strings.TrimSpace(t)) {
case db.SuggestionTypeGrammar, db.SuggestionTypePhrasing, db.SuggestionTypeIdiom, db.SuggestionTypeClarity:
return strings.ToLower(strings.TrimSpace(t))
default:
return db.SuggestionTypeGrammar
}
}
// --- response helpers -------------------------------------------------------
func writeJSON(w http.ResponseWriter, status int, v any) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(v)
}
func errorJSON(w http.ResponseWriter, status int, msg string) {
writeJSON(w, status, map[string]string{"error": msg})
}
func serverError(w http.ResponseWriter, err error) {
errorJSON(w, http.StatusInternalServerError, err.Error())
}

142
internal/suggestions/handlers_test.go Normal file
View File

@@ -0,0 +1,142 @@
package suggestions
import (
"bytes"
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"path/filepath"
"testing"
"github.com/go-chi/chi/v5"
"gitea.parodia.dev/drwily/petal/internal/db"
"gitea.parodia.dev/drwily/petal/internal/llm"
)
// stubClient returns a canned checkpoint response; it never touches the network.
type stubClient struct {
response string
calls int
}
func (s *stubClient) Complete(_ context.Context, _ llm.CompletionRequest) (string, error) {
s.calls++
return s.response, nil
}
func (s *stubClient) Stream(_ context.Context, _ llm.CompletionRequest) (<-chan string, error) {
ch := make(chan string)
close(ch)
return ch, nil
}
// newTestServer wires a real DB, a seeded document, and the suggestion routes
// (both the doc-scoped and the per-suggestion mounts) onto one router.
func newTestServer(t *testing.T, client llm.LLMClient) (http.Handler, string) {
t.Helper()
database, err := db.Open(filepath.Join(t.TempDir(), "test.db"))
if err != nil {
t.Fatalf("open db: %v", err)
}
t.Cleanup(func() { database.Close() })
// Seed a document with some content to check.
var docID string
err = database.QueryRow(
`INSERT INTO documents (user_id, content_text) VALUES (?, ?) RETURNING id`,
db.LocalUserID, "I has two apple.",
).Scan(&docID)
if err != nil {
t.Fatalf("seed doc: %v", err)
}
h := New(database, client)
r := chi.NewRouter()
r.Route("/docs", func(dr chi.Router) { h.RegisterDocRoutes(dr) })
r.Mount("/suggestions", h.Routes())
return r, docID
}
func do(t *testing.T, srv http.Handler, method, path, body string) *httptest.ResponseRecorder {
t.Helper()
var r *http.Request
if body != "" {
r = httptest.NewRequest(method, path, bytes.NewBufferString(body))
} else {
r = httptest.NewRequest(method, path, nil)
}
rec := httptest.NewRecorder()
srv.ServeHTTP(rec, r)
return rec
}
func TestCheckpointFlow(t *testing.T) {
client := &stubClient{response: `{"suggestions":[
{"original":"I has","replacement":"I have","explanation":"subject-verb agreement","type":"grammar"},
{"original":"two apple","replacement":"two apples","explanation":"plural noun","type":"grammar"}
]}`}
srv, docID := newTestServer(t, client)
// Run a checkpoint → two pending suggestions, with positions located.
rec := do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
if rec.Code != http.StatusOK {
t.Fatalf("check: code=%d body=%s", rec.Code, rec.Body)
}
var got []db.Suggestion
if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
t.Fatalf("decode: %v", err)
}
if len(got) != 2 {
t.Fatalf("want 2 suggestions, got %d: %+v", len(got), got)
}
if got[0].Original != "I has" || got[0].FromPos != 0 {
t.Fatalf("first suggestion anchoring wrong: %+v", got[0])
}
if got[0].Status != db.SuggestionStatusPending {
t.Fatalf("new suggestion should be pending: %+v", got[0])
}
// Listing returns the same pending set.
rec = do(t, srv, http.MethodGet, "/docs/"+docID+"/suggestions", "")
var listed []db.Suggestion
_ = json.Unmarshal(rec.Body.Bytes(), &listed)
if len(listed) != 2 {
t.Fatalf("list pending: want 2, got %d", len(listed))
}
// Accept the first, dismiss the second.
if rec = do(t, srv, http.MethodPost, "/suggestions/"+got[0].ID+"/accept", ""); rec.Code != http.StatusNoContent {
t.Fatalf("accept: code=%d body=%s", rec.Code, rec.Body)
}
if rec = do(t, srv, http.MethodPost, "/suggestions/"+got[1].ID+"/dismiss", ""); rec.Code != http.StatusNoContent {
t.Fatalf("dismiss: code=%d body=%s", rec.Code, rec.Body)
}
// Pending list is now empty (accepted/dismissed are excluded).
rec = do(t, srv, http.MethodGet, "/docs/"+docID+"/suggestions", "")
_ = json.Unmarshal(rec.Body.Bytes(), &listed)
if len(listed) != 0 {
t.Fatalf("pending after resolve: want 0, got %d", len(listed))
}
// Re-accepting an already-resolved suggestion 404s.
if rec = do(t, srv, http.MethodPost, "/suggestions/"+got[0].ID+"/accept", ""); rec.Code != http.StatusNotFound {
t.Fatalf("re-accept: want 404, got %d", rec.Code)
}
}
func TestCheckpointRateLimit(t *testing.T) {
client := &stubClient{response: `{"suggestions":[{"original":"I has","replacement":"I have","explanation":"x","type":"grammar"}]}`}
srv, docID := newTestServer(t, client)
// First check runs the model.
do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
// Immediate second check is throttled — returns the existing set without
// hitting the model again.
do(t, srv, http.MethodPost, "/docs/"+docID+"/check", "")
if client.calls != 1 {
t.Fatalf("rate limit should suppress the second model call, got %d calls", client.calls)
}
}