Skip to content

[FEAT] Build LLM microservice for structured card generation #91

Description

@MikeNovikoff

Feature description

Implement a standalone Python/FastAPI microservice (llm-service) responsible for all AI-powered card generation. The service must communicate with OpenRouter (OpenAI-compatible API) and return strictly validated JSON using Pydantic structured outputs.

What is needed to be done

Scope

llm-service/server.py: FastAPI app with /health and /generate
llm-service/generator.py: OpenAI client wrapper, Pydantic models (MultipleChoiceCard, SingleAnswerCard), system prompts
llm-service/Dockerfile: Python 3.13-slim image
Environment: OPENROUTER_API_KEY, LLM_MODEL (default: openai/gpt-oss-20b:free)

Acceptance Criteria

  • POST /generate accepts text, card_type (multiple_choice|single_answer), and count (1–20)
  • Returns JSON array of cards with type, question, options, correct_indices, correct_answer, hint
  • MultipleChoiceCard generates exactly 4 options with 0-based correct indices
  • SingleAnswerCard generates a free-text correct answer
  • GET /health returns {"status":"ok"}
  • Service is containerized and starts with uvicorn

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

Status
No status

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions