---
title: MyPal (9XAIPal)
emoji: 📚
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: mit
---

# 9XAIPal — local-first reading companion

Single-container Hugging Face Space deployment. A plain FastAPI app (`app.py`)
mounts the real 9XAIPal backend API at `/api/v1` and serves the compiled React
UI at `/` (SPA with client-side routing) — all on port `7860`.

## Layout

| Path              | Purpose                                            |
| ----------------- | -------------------------------------------------- |
| `app.py`          | FastAPI entrypoint (API + SPA, port 7860)          |
| `Dockerfile`      | Builds the image; bakes in the Ollama embedder     |
| `start.sh`        | Boot script: Redis, Ollama, then supervisord (API + Celery worker + optional local Postgres) |
| `supervisord.conf`| Process supervisor config: keeps API + worker alive |
| `requirements.txt`| Python dependencies                                |
| `app/`            | 9XAIPal backend package                            |
| `dist/`           | Compiled React UI                                  |

## Links

- **YouTube Demo Video:** [https://youtu.be/m-uIaNKOOrk?si=4FpcZtlKJwZpPJnz](https://youtu.be/m-uIaNKOOrk?si=4FpcZtlKJwZpPJnz)
- **GitHub Repository:** [https://github.com/Khaled-Saleh-KL1/9XAIPal](https://github.com/Khaled-Saleh-KL1/9XAIPal)
- **X (Twitter) Post:** [https://x.com/KL1_Suii/status/2066237932713775393?s=20](https://x.com/KL1_Suii/status/2066237932713775393?s=20)

## Configuration (set as Space **Secrets / Variables**)

All config is read from environment variables — **no `.env` file is bundled**.
Set these under *Settings → Variables and secrets*:

- `OLLAMA_BASE_URL`, `OLLAMA_API_KEY` — chat/VLM backend (Ollama Cloud)
- `CHAT_MODEL`, `VLM_MODEL` — **must match an exact tag served by your
  `OLLAMA_BASE_URL`**. If the endpoint lists `gemma4:31b` and not
  `gemma4:31b-cloud`, set `CHAT_MODEL=gemma4:31b` and `VLM_MODEL=gemma4:31b`.
- `EMBEDDING_PROVIDER=ollama`, `EMBEDDING_BASE_URL=http://localhost:11434`,
  `EMBEDDING_MODEL=qwen3-embedding` — embeddings run on the **in-container**
  Ollama (the 31B chat model lives on Ollama Cloud, which hosts no embedding
  models, so a small embedding model is baked into the image and served locally)
- `HF_TOKEN` / `HUGGING_FACE_HUB_TOKEN` — model-weight downloads
- **Database** — `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`,
  `POSTGRES_USER`, `POSTGRES_PASSWORD`, `PGSSLMODE=require`. The Space container
  disk is **ephemeral**, so this deployment points at an **external managed
  Postgres** (Supabase, with `pgvector`) so uploaded papers persist across
  restarts/rebuilds. Use Supabase's **session-mode connection pooler** host
  (`aws-0-<region>.pooler.supabase.com:5432`, user `postgres.<project-ref>`) —
  the direct `db.<ref>.supabase.co` host is IPv6-only and unreachable from the
  IPv4-only Space container.
- (optional) `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `GEMINI_API_KEY` / … for cloud fallback

> Note: `start.sh` boots Redis and an in-container Ollama (for embeddings), then
> launches `supervisord` to keep the FastAPI app **and a Celery worker** alive.
> PostgreSQL runs **externally** (managed) whenever `POSTGRES_HOST` is set to a
> non-local host — the bundled in-container Postgres is started only as a fallback
> for local/no-external-DB runs, and its data is ephemeral. Redis here is just an
> ephemeral cache/queue.
>
> **PDF extraction:** the image enables the PyMuPDF text-only fallback by default
> (`ALLOW_PYMUPDF_FALLBACK=1`) so uploads process immediately without baking
> several gigabytes of MinerU + torch into the image. For higher-fidelity output
> (OCR, tables, equations, figures), install `mineru[pipeline]>=3.2.0`, `torch`,
> `torchvision`, and `scipy>=1.17.1` in `requirements.txt` and set
> `ALLOW_PYMUPDF_FALLBACK=0` (or unset) in the Space variables.
>
> **Self-healing:** the container has a Docker `HEALTHCHECK` on `/healthz` and an
> in-app watchdog that detects stuck ingestion jobs. If a paper hangs in
> `queued` / `extracting` / `chunking` / `embedding` / `summarizing` for too long,
> the watchdog revokes the stuck Celery task, cleans up partial state, and
> re-dispatches the job so processing completes.