README.md

---
title: MyVillage Activity Composition API
emoji: 🧩
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
models:
- mjpsm/activity-composition-model-400-qwen3.5-0.8b-gguf
---

# MyVillage Activity Composition API

A simple FastAPI API that loads the Q8_0 GGUF directly with `llama-cpp-python`.

There is **no separate llama-server process**.

The only web server is Uvicorn:

```text
uvicorn main:app --host 0.0.0.0 --port 7860
```

## Model

- Source model: `mjpsm/activity-composition-model-400-qwen3.5-0.8b`
- GGUF repo: `mjpsm/activity-composition-model-400-qwen3.5-0.8b-gguf`
- GGUF file: `activity-composition-model-400-qwen3.5-0.8b-Q8_0.gguf`
- Runtime: `llama-cpp-python`

## Endpoints

- `GET /`
- `GET /health`
- `GET /model`
- `POST /generate`
- `GET /docs`

## Request

```json
{
  "progression": {
    "knowledge_state": "PARTIAL",
    "demonstrated_state": [
      "Created the initial animation and added the first set of assets"
    ],
    "next_gap": "Finish and polish the remaining animation work",
    "activity_plan": {
      "action": "complete the remaining animation work",
      "target": "the animation",
      "avoid_repeating": [
        "recreating the initial animation",
        "re-adding assets already included"
      ]
    }
  }
}
```

## Response

```json
{
  "output": {
    "activity_title": "string",
    "activity_description": "string"
  }
}
```

## Private GGUF repo

If the GGUF repo is private, add a Space secret named:

`HF_TOKEN`

with read access to the model repository.

## Architecture

```text
Client
  ↓
Uvicorn
  ↓
FastAPI
  ↓
llama-cpp-python
  ↓
Q8_0 GGUF
  ↓
validated Composition JSON
```