feat: add diagnostic interview loop

This commit is contained in:
user
2026-04-26 16:24:35 +09:00
parent 0e232ff405
commit 4a4240fea2
21 changed files with 926 additions and 23 deletions

View File

@@ -5,12 +5,15 @@ import (
"tutor/internal/config"
"tutor/internal/httpapi"
"tutor/internal/interview"
"tutor/internal/workflows"
)
func NewServer(cfg config.Config) *http.Server {
runner := workflows.NewStubRunner()
handler := httpapi.NewHandler(cfg, runner)
store := interview.NewMemoryStore()
service := interview.NewService(store, runner)
handler := httpapi.NewHandler(cfg, service)
return &http.Server{
Addr: cfg.HTTPAddr,

View File

@@ -0,0 +1,80 @@
package httpapi
import (
"encoding/json"
"errors"
"net/http"
"tutor/internal/interview"
)
type createDiagnosticSessionRequest struct {
UserID string `json:"user_id"`
TargetRole string `json:"target_role"`
Stack []string `json:"stack"`
InterviewTimeline string `json:"interview_timeline"`
}
type submitDiagnosticAnswerRequest struct {
QuestionID string `json:"question_id"`
AnswerText string `json:"answer_text"`
}
func (h Handler) createDiagnosticSession(w http.ResponseWriter, r *http.Request) {
var req createDiagnosticSessionRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeError(w, http.StatusBadRequest, "invalid JSON body")
return
}
session, err := h.diagnostic.CreateSession(r.Context(), interview.CreateSessionInput{
UserID: req.UserID,
TargetRole: req.TargetRole,
Stack: req.Stack,
InterviewTimeline: req.InterviewTimeline,
})
if err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusCreated, session)
}
func (h Handler) getDiagnosticSession(w http.ResponseWriter, r *http.Request) {
session, err := h.diagnostic.GetSession(r.PathValue("id"))
if errors.Is(err, interview.ErrSessionNotFound) {
writeError(w, http.StatusNotFound, "diagnostic session not found")
return
}
if err != nil {
writeError(w, http.StatusInternalServerError, "could not load diagnostic session")
return
}
writeJSON(w, http.StatusOK, session)
}
func (h Handler) submitDiagnosticAnswer(w http.ResponseWriter, r *http.Request) {
var req submitDiagnosticAnswerRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeError(w, http.StatusBadRequest, "invalid JSON body")
return
}
answer, err := h.diagnostic.SubmitAnswer(r.Context(), interview.SubmitAnswerInput{
SessionID: r.PathValue("id"),
QuestionID: req.QuestionID,
AnswerText: req.AnswerText,
})
if errors.Is(err, interview.ErrSessionNotFound) || errors.Is(err, interview.ErrQuestionNotFound) {
writeError(w, http.StatusNotFound, err.Error())
return
}
if err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusCreated, answer)
}

View File

@@ -0,0 +1,76 @@
package httpapi
import (
"bytes"
"encoding/json"
"net/http"
"net/http/httptest"
"testing"
"tutor/internal/config"
"tutor/internal/interview"
"tutor/internal/workflows"
)
func TestDiagnosticHTTPFlow(t *testing.T) {
service := interview.NewService(interview.NewMemoryStore(), workflows.NewStubRunner())
handler := NewHandler(config.Config{Environment: "test", ModelKey: "deepseek-v4-flash"}, service)
routes := handler.Routes()
createBody := bytes.NewBufferString(`{
"user_id":"user-1",
"target_role":"junior backend developer",
"stack":["go","postgres"],
"interview_timeline":"30 days"
}`)
createReq := httptest.NewRequest(http.MethodPost, "/api/v1/diagnostic-sessions", createBody)
createRec := httptest.NewRecorder()
routes.ServeHTTP(createRec, createReq)
if createRec.Code != http.StatusCreated {
t.Fatalf("create status = %d, body = %s", createRec.Code, createRec.Body.String())
}
var session interview.Session
if err := json.NewDecoder(createRec.Body).Decode(&session); err != nil {
t.Fatalf("decode create response: %v", err)
}
if len(session.Questions) == 0 {
t.Fatal("expected questions")
}
answerBody := bytes.NewBufferString(`{
"question_id":"` + session.Questions[0].ID + `",
"answer_text":"Idempotent requests can be retried safely because repeated calls have the same intended effect."
}`)
answerReq := httptest.NewRequest(http.MethodPost, "/api/v1/diagnostic-sessions/"+session.ID+"/answers", answerBody)
answerRec := httptest.NewRecorder()
routes.ServeHTTP(answerRec, answerReq)
if answerRec.Code != http.StatusCreated {
t.Fatalf("answer status = %d, body = %s", answerRec.Code, answerRec.Body.String())
}
var answer interview.Answer
if err := json.NewDecoder(answerRec.Body).Decode(&answer); err != nil {
t.Fatalf("decode answer response: %v", err)
}
if len(answer.Grade.Evidence) == 0 {
t.Fatal("expected grade evidence")
}
getReq := httptest.NewRequest(http.MethodGet, "/api/v1/diagnostic-sessions/"+session.ID, nil)
getRec := httptest.NewRecorder()
routes.ServeHTTP(getRec, getReq)
if getRec.Code != http.StatusOK {
t.Fatalf("get status = %d, body = %s", getRec.Code, getRec.Body.String())
}
var loaded interview.Session
if err := json.NewDecoder(getRec.Body).Decode(&loaded); err != nil {
t.Fatalf("decode get response: %v", err)
}
if len(loaded.Answers) != 1 {
t.Fatalf("answers = %d, want 1", len(loaded.Answers))
}
}

View File

@@ -5,24 +5,27 @@ import (
"net/http"
"tutor/internal/config"
"tutor/internal/workflows"
"tutor/internal/interview"
)
type Handler struct {
cfg config.Config
runner workflows.Runner
cfg config.Config
diagnostic *interview.Service
}
func NewHandler(cfg config.Config, runner workflows.Runner) Handler {
func NewHandler(cfg config.Config, diagnostic *interview.Service) Handler {
return Handler{
cfg: cfg,
runner: runner,
cfg: cfg,
diagnostic: diagnostic,
}
}
func (h Handler) Routes() http.Handler {
mux := http.NewServeMux()
mux.HandleFunc("GET /healthz", h.health)
mux.HandleFunc("POST /api/v1/diagnostic-sessions", h.createDiagnosticSession)
mux.HandleFunc("GET /api/v1/diagnostic-sessions/{id}", h.getDiagnosticSession)
mux.HandleFunc("POST /api/v1/diagnostic-sessions/{id}/answers", h.submitDiagnosticAnswer)
return mux
}
@@ -45,3 +48,11 @@ func writeJSON(w http.ResponseWriter, status int, value any) {
w.WriteHeader(status)
_ = json.NewEncoder(w).Encode(value)
}
func writeError(w http.ResponseWriter, status int, message string) {
writeJSON(w, status, errorResponse{Error: message})
}
type errorResponse struct {
Error string `json:"error"`
}

View File

@@ -7,6 +7,7 @@ import (
"testing"
"tutor/internal/config"
"tutor/internal/interview"
"tutor/internal/workflows"
)
@@ -15,7 +16,8 @@ func TestHealth(t *testing.T) {
Environment: "test",
ModelKey: "deepseek-v4-flash",
}
handler := NewHandler(cfg, workflows.NewStubRunner())
service := interview.NewService(interview.NewMemoryStore(), workflows.NewStubRunner())
handler := NewHandler(cfg, service)
req := httptest.NewRequest(http.MethodGet, "/healthz", nil)
rec := httptest.NewRecorder()

View File

@@ -0,0 +1,29 @@
package interview
import "tutor/internal/workflows"
func BackendDeveloperQuestions() []Question {
return []Question{
{
ID: "backend-http-idempotency",
Prompt: "What makes an HTTP method idempotent, and why does that matter for retries?",
Concepts: []workflows.ConceptRef{
{ID: "http-idempotency", Label: "HTTP idempotency", Track: BackendDeveloperTrack},
},
},
{
ID: "backend-db-index-tradeoff",
Prompt: "When would adding a database index improve an API, and what tradeoffs can it introduce?",
Concepts: []workflows.ConceptRef{
{ID: "database-indexes", Label: "Database indexes", Track: BackendDeveloperTrack},
},
},
{
ID: "backend-cache-invalidation",
Prompt: "How would you decide whether to cache an API response, and how would you handle stale data?",
Concepts: []workflows.ConceptRef{
{ID: "cache-invalidation", Label: "Cache invalidation", Track: BackendDeveloperTrack},
},
},
}
}

View File

@@ -0,0 +1,117 @@
package interview
import (
"context"
"errors"
"fmt"
"strings"
"sync/atomic"
"time"
"tutor/internal/workflows"
)
var ErrQuestionNotFound = errors.New("diagnostic question not found")
type Service struct {
store Store
runner workflows.Runner
ids atomic.Uint64
}
func NewService(store Store, runner workflows.Runner) *Service {
return &Service{store: store, runner: runner}
}
func (s *Service) CreateSession(_ context.Context, input CreateSessionInput) (Session, error) {
if strings.TrimSpace(input.UserID) == "" {
return Session{}, errors.New("user_id is required")
}
if strings.TrimSpace(input.TargetRole) == "" {
return Session{}, errors.New("target_role is required")
}
if len(input.Stack) == 0 {
return Session{}, errors.New("stack is required")
}
session := Session{
ID: s.nextID("diag"),
UserID: input.UserID,
Track: BackendDeveloperTrack,
Status: SessionInProgress,
TargetRole: input.TargetRole,
Stack: append([]string(nil), input.Stack...),
InterviewTimeline: input.InterviewTimeline,
Questions: BackendDeveloperQuestions(),
CreatedAt: time.Now().UTC(),
}
return s.store.Create(session)
}
func (s *Service) GetSession(id string) (Session, error) {
return s.store.Get(id)
}
func (s *Service) SubmitAnswer(ctx context.Context, input SubmitAnswerInput) (Answer, error) {
if strings.TrimSpace(input.AnswerText) == "" {
return Answer{}, errors.New("answer_text is required")
}
session, err := s.store.Get(input.SessionID)
if err != nil {
return Answer{}, err
}
question, ok := findQuestion(session.Questions, input.QuestionID)
if !ok {
return Answer{}, ErrQuestionNotFound
}
answer := Answer{
ID: s.nextID("answer"),
QuestionID: input.QuestionID,
Text: input.AnswerText,
CreatedAt: time.Now().UTC(),
}
grade, err := s.runner.GradeInterviewAnswer(ctx, workflows.GradeAnswerInput{
UserID: session.UserID,
QuestionID: question.ID,
AnswerID: answer.ID,
AnswerText: answer.Text,
Concepts: question.Concepts,
})
if err != nil {
return Answer{}, err
}
answer.Grade = grade
session.Answers = append(session.Answers, answer)
if answeredQuestionCount(session.Answers) >= len(session.Questions) {
session.Status = SessionComplete
}
if _, err := s.store.Update(session); err != nil {
return Answer{}, err
}
return answer, nil
}
func answeredQuestionCount(answers []Answer) int {
answered := make(map[string]struct{}, len(answers))
for _, answer := range answers {
answered[answer.QuestionID] = struct{}{}
}
return len(answered)
}
func (s *Service) nextID(prefix string) string {
return fmt.Sprintf("%s-%d", prefix, s.ids.Add(1))
}
func findQuestion(questions []Question, id string) (Question, bool) {
for _, question := range questions {
if question.ID == id {
return question, true
}
}
return Question{}, false
}

View File

@@ -0,0 +1,87 @@
package interview
import (
"context"
"testing"
"tutor/internal/workflows"
)
func TestDiagnosticSessionAnswerFlow(t *testing.T) {
service := NewService(NewMemoryStore(), workflows.NewStubRunner())
session, err := service.CreateSession(context.Background(), CreateSessionInput{
UserID: "user-1",
TargetRole: "junior backend developer",
Stack: []string{"go", "postgres"},
})
if err != nil {
t.Fatalf("CreateSession error: %v", err)
}
if session.Track != BackendDeveloperTrack {
t.Fatalf("Track = %q", session.Track)
}
if session.Status != SessionInProgress {
t.Fatalf("Status = %q, want %q", session.Status, SessionInProgress)
}
if len(session.Questions) == 0 {
t.Fatal("expected diagnostic questions")
}
answer, err := service.SubmitAnswer(context.Background(), SubmitAnswerInput{
SessionID: session.ID,
QuestionID: session.Questions[0].ID,
AnswerText: "Idempotent methods can be retried safely because repeated calls have the same intended effect.",
})
if err != nil {
t.Fatalf("SubmitAnswer error: %v", err)
}
if answer.Grade.AnswerID != answer.ID {
t.Fatalf("grade answer id = %q, want %q", answer.Grade.AnswerID, answer.ID)
}
if len(answer.Grade.Concepts) == 0 {
t.Fatal("expected graded concepts")
}
if len(answer.Grade.Evidence) == 0 {
t.Fatal("expected grading evidence")
}
loaded, err := service.GetSession(session.ID)
if err != nil {
t.Fatalf("GetSession error: %v", err)
}
if len(loaded.Answers) != 1 {
t.Fatalf("answers = %d, want 1", len(loaded.Answers))
}
}
func TestDiagnosticSessionCompletesAfterAllQuestionsAnswered(t *testing.T) {
service := NewService(NewMemoryStore(), workflows.NewStubRunner())
session, err := service.CreateSession(context.Background(), CreateSessionInput{
UserID: "user-1",
TargetRole: "junior backend developer",
Stack: []string{"go"},
})
if err != nil {
t.Fatalf("CreateSession error: %v", err)
}
for _, question := range session.Questions {
if _, err := service.SubmitAnswer(context.Background(), SubmitAnswerInput{
SessionID: session.ID,
QuestionID: question.ID,
AnswerText: "This answer gives a concrete backend tradeoff with an operational example for the interview.",
}); err != nil {
t.Fatalf("SubmitAnswer(%s) error: %v", question.ID, err)
}
}
loaded, err := service.GetSession(session.ID)
if err != nil {
t.Fatalf("GetSession error: %v", err)
}
if loaded.Status != SessionComplete {
t.Fatalf("Status = %q, want %q", loaded.Status, SessionComplete)
}
}

View File

@@ -0,0 +1,62 @@
package interview
import (
"errors"
"sync"
)
var ErrSessionNotFound = errors.New("diagnostic session not found")
type Store interface {
Create(Session) (Session, error)
Get(string) (Session, error)
Update(Session) (Session, error)
}
type MemoryStore struct {
mu sync.RWMutex
sessions map[string]Session
}
func NewMemoryStore() *MemoryStore {
return &MemoryStore{
sessions: make(map[string]Session),
}
}
func (s *MemoryStore) Create(session Session) (Session, error) {
s.mu.Lock()
defer s.mu.Unlock()
s.sessions[session.ID] = cloneSession(session)
return session, nil
}
func (s *MemoryStore) Get(id string) (Session, error) {
s.mu.RLock()
defer s.mu.RUnlock()
session, ok := s.sessions[id]
if !ok {
return Session{}, ErrSessionNotFound
}
return cloneSession(session), nil
}
func (s *MemoryStore) Update(session Session) (Session, error) {
s.mu.Lock()
defer s.mu.Unlock()
if _, ok := s.sessions[session.ID]; !ok {
return Session{}, ErrSessionNotFound
}
s.sessions[session.ID] = cloneSession(session)
return session, nil
}
func cloneSession(session Session) Session {
session.Stack = append([]string(nil), session.Stack...)
session.Questions = append([]Question(nil), session.Questions...)
session.Answers = append([]Answer(nil), session.Answers...)
return session
}

View File

@@ -0,0 +1,56 @@
package interview
import (
"time"
"tutor/internal/workflows"
)
const BackendDeveloperTrack = "backend-developer"
type SessionStatus string
const (
SessionInProgress SessionStatus = "in_progress"
SessionComplete SessionStatus = "complete"
)
type Session struct {
ID string `json:"id"`
UserID string `json:"user_id"`
Track string `json:"track"`
Status SessionStatus `json:"status"`
TargetRole string `json:"target_role"`
Stack []string `json:"stack"`
InterviewTimeline string `json:"interview_timeline,omitempty"`
Questions []Question `json:"questions"`
Answers []Answer `json:"answers"`
CreatedAt time.Time `json:"created_at"`
}
type Question struct {
ID string `json:"id"`
Prompt string `json:"prompt"`
Concepts []workflows.ConceptRef `json:"concepts"`
}
type Answer struct {
ID string `json:"id"`
QuestionID string `json:"question_id"`
Text string `json:"text"`
Grade workflows.GradedAnswer `json:"grade"`
CreatedAt time.Time `json:"created_at"`
}
type CreateSessionInput struct {
UserID string
TargetRole string
Stack []string
InterviewTimeline string
}
type SubmitAnswerInput struct {
SessionID string
QuestionID string
AnswerText string
}

View File

@@ -58,6 +58,7 @@ type GradedAnswer struct {
Overall AnswerOverall `json:"overall"`
Strengths []string `json:"strengths"`
Gaps []string `json:"gaps"`
Evidence []EvidenceRef `json:"evidence"`
MisconceptionCandidates []MisconceptionCandidate `json:"misconception_candidates"`
FollowUp FollowUpRecommendation `json:"follow_up"`
}

View File

@@ -3,6 +3,7 @@ package workflows
import (
"context"
"errors"
"strings"
)
var ErrNotImplemented = errors.New("workflow runner not implemented")
@@ -27,6 +28,7 @@ type GradeAnswerInput struct {
QuestionID string
AnswerID string
AnswerText string
Concepts []ConceptRef
}
type NextChallengeInput struct {
@@ -49,8 +51,49 @@ func (StubRunner) DiagnoseJobSeeker(context.Context, DiagnosticInput) (Diagnosti
return DiagnosticResult{}, ErrNotImplemented
}
func (StubRunner) GradeInterviewAnswer(context.Context, GradeAnswerInput) (GradedAnswer, error) {
return GradedAnswer{}, ErrNotImplemented
func (StubRunner) GradeInterviewAnswer(_ context.Context, input GradeAnswerInput) (GradedAnswer, error) {
wordCount := len(strings.Fields(input.AnswerText))
overall := AnswerPartial
if wordCount >= 18 {
overall = AnswerSolid
}
if wordCount < 8 {
overall = AnswerMiss
}
grade := GradedAnswer{
AnswerID: input.AnswerID,
QuestionID: input.QuestionID,
Concepts: append([]ConceptRef(nil), input.Concepts...),
Scores: AnswerScores{
Correctness: scoreFromWords(wordCount, 8),
Depth: scoreFromWords(wordCount, 14),
Communication: scoreFromWords(wordCount, 10),
ProductionJudgment: scoreFromWords(wordCount, 20),
},
Overall: overall,
Strengths: []string{"Answer was captured and evaluated through the typed workflow boundary."},
Gaps: []string{},
Evidence: []EvidenceRef{
{
Kind: EvidenceAnswer,
ID: input.AnswerID,
Quote: input.AnswerText,
Confidence: 1,
},
},
FollowUp: FollowUpRecommendation{},
}
if overall == AnswerMiss || overall == AnswerPartial {
grade.Gaps = []string{"Answer needs more concrete reasoning and tradeoff discussion."}
grade.FollowUp = FollowUpRecommendation{
Needed: true,
Question: "Can you give a concrete production example and explain the tradeoff?",
Purpose: FollowUpRepair,
}
}
return grade, nil
}
func (StubRunner) ExtractLearningMemory(context.Context, GradedAnswer) (MemoryUpdateCandidate, error) {
@@ -64,3 +107,13 @@ func (StubRunner) SelectNextChallenge(context.Context, NextChallengeInput) (Next
func (StubRunner) UpdateReadinessMap(context.Context, ReadinessUpdateInput) (ReadinessUpdate, error) {
return ReadinessUpdate{}, ErrNotImplemented
}
func scoreFromWords(wordCount int, target int) int {
if wordCount >= target {
return 4
}
if wordCount >= target/2 {
return 2
}
return 1
}

View File

@@ -6,7 +6,7 @@ import (
"testing"
)
func TestStubRunnerReturnsTypedNotImplemented(t *testing.T) {
func TestStubRunnerDiagnoseReturnsTypedNotImplemented(t *testing.T) {
runner := NewStubRunner()
_, err := runner.DiagnoseJobSeeker(context.Background(), DiagnosticInput{
@@ -19,3 +19,28 @@ func TestStubRunnerReturnsTypedNotImplemented(t *testing.T) {
t.Fatalf("err = %v, want %v", err, ErrNotImplemented)
}
}
func TestStubRunnerGradesAnswer(t *testing.T) {
runner := NewStubRunner()
grade, err := runner.GradeInterviewAnswer(context.Background(), GradeAnswerInput{
QuestionID: "q-1",
AnswerID: "a-1",
AnswerText: "Indexes can speed reads by helping the database find rows, but they add write overhead.",
Concepts: []ConceptRef{
{ID: "database-indexes", Label: "Database indexes", Track: "backend-developer"},
},
})
if err != nil {
t.Fatalf("GradeInterviewAnswer error: %v", err)
}
if grade.AnswerID != "a-1" {
t.Fatalf("AnswerID = %q", grade.AnswerID)
}
if len(grade.Concepts) != 1 {
t.Fatalf("concepts = %d, want 1", len(grade.Concepts))
}
if len(grade.Evidence) != 1 {
t.Fatalf("evidence = %d, want 1", len(grade.Evidence))
}
}