README.md

---
title: PSYCHE web
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
---

# PSYCHE web (Hugging Face Space)

Barebones **Flask** app: **Home**, **Analysis** (DuckDB + preset queries over demo CSV), **Replay** (placeholder).

This Space uses **Flask + gunicorn**, not the FastAPI starter Hugging Face shows in the empty-Space wizard. That is intentional.

**Live Space:** [https://huggingface.co/spaces/ystrittm/psyche](https://huggingface.co/spaces/ystrittm/psyche)

## Run locally

From this directory:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
export FLASK_APP=app.py
flask run --host 0.0.0.0 --port 7860
```

Open `http://127.0.0.1:7860/`.

---

## Deploy without a second repo (work only in PSYCHE)

Hugging Face’s onboarding often shows:

```bash
git clone https://huggingface.co/spaces/ystrittm/psyche
# password = HF access token (write) from https://huggingface.co/settings/tokens
```

That clones the **Space’s own Git repository** on Hugging Face (not GitHub). It is **valid**: you edit there, then `git push` with the same token. Many people work that way.

For PSYCHE we also support **not** maintaining that second clone: keep **one** checkout of [PSYCHE on GitHub](https://github.com/younesStrittmatter/PSYCHE), edit `space/` here, and deploy with the options below (they push the `space/` subtree to the same HF URL).

### Hugging Face does not “connect” a GitHub repo in Space settings

There is **no** reliable toggle like “use this GitHub repo as the source” in the Space UI. **Rename or transfer** only changes **owner or name** (and the Space URL / git remote); it does **not** sync GitHub.

To deploy the `space/` folder from PSYCHE, use one of the options below.

### Option A — Push from your machine (simplest)

From the **PSYCHE** repo root, **`space/` must be committed** (the push script uses `git subtree split`, which only sees tracked files):

```bash
git add space
git commit -m "Add Hugging Face Space app"
```

Then:

```bash
export HF_TOKEN=hf_...   # write token: https://huggingface.co/settings/tokens
./scripts/push_hf_space.sh
```

**Using a `.env` file:** copy [`.env.example`](../.env.example) to **`.env`** in the repo root (`.env` is gitignored), put `HF_TOKEN=hf_...` inside, then run `./scripts/push_hf_space.sh` — the script loads `.env` automatically.

If you already use **`source scripts/activate.sh`** with a secrets file ([`scripts/local.env.example`](../scripts/local.env.example)), putting `export HF_TOKEN=...` in that secrets file also works before running the script.

That uses `git subtree split` to push **only** the `space/` tree to `spaces/ystrittm/psyche` (no second working copy). If the Space still has the default FastAPI starter and push is rejected, run **once**:

```bash
HF_SPACE_FORCE=1 ./scripts/push_hf_space.sh
```

Optional: `HF_USERNAME` (your HF username) if `oauth2` as user does not work with your token setup.

### Option B — GitHub Actions (push to GitHub → Space updates)

This repo includes **[`.github/workflows/sync-psyche-space.yml`](../.github/workflows/sync-psyche-space.yml)**. Add a repository secret **`HF_TOKEN`** (same write token as above): GitHub → **Settings** → **Secrets and variables** → **Actions** → **New repository secret**.

When you push to **`main`** and **`space/`** changes, the workflow runs `scripts/push_hf_space.sh` so you do not have to run it locally.

### Option C — Second clone (optional)

You *can* clone `https://huggingface.co/spaces/ystrittm/psyche` elsewhere and copy from `space/`, but it duplicates work—prefer **A** or **B**.

---

Optional: add `HF_TOKEN` in **Space → Settings → Secrets** when the app reads private Hub data (not used by the current demo).

## GitHub → this URL

Set the PSYCHE GitHub repo **Website** to `https://huggingface.co/spaces/ystrittm/psyche` and link it from the root README / docs.