mjpsm/activity-generation-v1.3-api

MyVillage Activity Generation v1.3 API

Docker + FastAPI inference service for mjpsm/activity-generation-v1.3.

The runtime pins transformers==5.17.0 because the tokenizer artifacts saved with v1.3 use the Transformers v5 special-token format.

The API preserves the exact model-facing v1.3 contract used for supervised fine-tuning:

• —village_goal
• —previous_activity_title
• —knowledge_submission
• —one wisdom object with chapterTitle, bookName, bookTypeName, and content

Dataset-only metadata such as department, domain, difficulty, activity type, and submission quality is intentionally rejected by the API.

Endpoints

GET /health

Returns 200 when the model is loaded and 503 when the web service is alive but the model is unavailable.

POST /generate

Uses the deterministic v1.3 inference policy:

• —do_sample=false
• —max_new_tokens=180
• —repetition_penalty=1.05

Example request:

{
  "village_goal": "Build confidence creating simple Python programs.",
  "previous_activity_title": "Test a Python Function",
  "knowledge_submission": "I tested three numbers and one gave the wrong answer.",
  "wisdom": {
    "chapterTitle": "Errors Give Direction",
    "bookName": "Learning Through the Bugs",
    "bookTypeName": "Proverbs",
    "content": "A mistake can reveal where understanding still needs to grow."
  }
}

Example response shape:

{
  "request_id": "uuid",
  "api_version": "1.0",
  "model": "mjpsm/activity-generation-v1.3",
  "activity": {
    "activity_title": "...",
    "activity_description": "...",
    "activity_instructions": "..."
  },
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  },
  "generation": {
    "generation_time_seconds": 0.0,
    "sampling": false
  }
}

POST /generate-pair

Generates Candidate A and Candidate B independently from the same prompt using:

• —do_sample=true
• —temperature=0.7
• —top_p=0.9
• —max_new_tokens=180
• —repetition_penalty=1.05

Candidate A is held fixed. Candidate B is regenerated up to three times when the normalized pair similarity is at or above 0.92. If all B attempts remain too similar, the least-similar B is returned with similarity_warning=true rather than failing the request.

generation_attempts and token usage count every real model generation, including malformed-output retries and similarity retries.

Validation and retries

The model output must be one JSON object containing exactly:

{
  "activity_title": "...",
  "activity_description": "...",
  "activity_instructions": "..."
}

Malformed output is retried up to two times after the initial attempt. Input validation failures return 422, unavailable-model requests return 503, and exhausted generation failures return 500 without exposing server stack traces.

Request IDs

Every successful API response contains a generated request_id. Every HTTP response also includes the same value in the X-Request-ID header so DPO records can be matched to service logs.

Local run

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 7860

Interactive API documentation is available at /docs after startup.

Tests

The test suite uses a fake model service, so it does not download the Hugging Face model.

pip install -r requirements-dev.txt
pytest -q

Docker

docker build -t activity-generation-v1.3-api .
docker run --rm -p 7860:7860 activity-generation-v1.3-api

Hugging Face Space

Create a Docker Space and upload the contents of this repository. The included README metadata and Dockerfile expose the service on port 7860.

The service automatically uses CUDA when available and otherwise falls back to CPU. The 0.5B model can run on CPU, although generation latency will be higher than on GPU hardware.

Optional environment configuration

The locked defaults can be overridden at deployment time if you intentionally version or experiment with the inference policy:

For the first DPO collection run, keep these defaults fixed so preference rows are produced under one consistent generation policy.