updated readme

README.md

@@ -1,28 +1,155 @@
----
-title: Mini Transformer Demo
-emoji: 🤖
-colorFrom: yellow
-colorTo: purple
-sdk: docker
-app_file: app.py
-pinned: false
-license: mit
----
-
-# Mini Transformer Demo
-
-Chainlit-powered dialogue interface that loads a mini encoder–decoder Transformer from `trained_models/` and serves it via Hugging Face Spaces. If you want the full project write-up, see [README.project.md](README.project.md).
-
-## Quickstart
-- Install deps: `pip install -r requirements.txt`.
-- Launch locally: `chainlit run app.py --host 0.0.0.0 --port 7860`.
-- Push to the Space: `git push hf main` (build triggers automatically).
-- Visit the Space URL once the build shows as *Running*.
-
-## Configuration
-- Place checkpoints under `trained_models/<model-name>/...` following the structure described in `README.project.md`.
-- Tweak Chainlit defaults with `.chainlit/config.toml`.
-- Use environment variables (e.g. `MINI_TRANSFORMER_MODELS`, `MINI_TRANSFORMER_MODEL_NAME`) to preselect models and configs.
-
-## Support
-Open an issue in this repo for bugs or feature requests. For deployment questions, check the [Spaces docs](https://huggingface.co/docs/hub/spaces-overview).
+# Mini-Transformer
+
+A compact, encoder–decoder Transformer packaged so it can be used both as a Python library and as a ready-to-run demo. The repository mirrors the installable package layout so cloning the repo or `pip install mini-transformer` gives the same structure and tooling.
+
+## Highlights
+- Typed, unit-tested implementation of an encoder–decoder Transformer with reusable building blocks (`mini_transformer/modules`).
+- Hydra configuration system with both packaged defaults (`mini_transformer/conf`) and editable configs in the repo.
+- Ready-made UIs: FastAPI REST server and Chainlit chat interface.
+- CLI convenience commands for inference, serving, UI launch, and Hugging Face model downloads.
+- Makefile shortcuts, notebooks, and Docker dev environment for day-to-day work.
+
+## Installation
+```bash
+# inside the repository (editable install with optional extras)
+pip install -e .[server,viz]
+```
+Or install the published package:
+```bash
+pip install "mini-transformer[server,viz]"
+```
+
+## Repository Layout
+- `src/mini_transformer/` – installable package (model code, CLI, apps, packaged Hydra configs).
+- `configs/` – editable Hydra configs for local experiments.
+- `trained_models/` – place downloaded or exported checkpoints here (see below).
+- `notebooks/` – exploratory notebooks (`train.ipynb`, `tokenizer.ipynb`, etc.).
+- `tests/` – unit and smoke tests.
+- Supporting files: `pyproject.toml`, `Makefile`, `Dockerfile.dev`, `environment.yml`, etc.
+
+## Training Notebook
+`notebooks/train.ipynb` demonstrates the Hydra-driven training loop used during development.
+- All hyper-parameters come from the composed config (see `configs/train_mode.yaml`); the key knobs live under `trainer.*`.
+- Checkpoint cadence is controlled by `trainer.save_interval` (in optimizer steps) and always saves on epoch boundaries.
+- Dataloader behaviour (workers, pinned memory) can be tuned via `trainer.num_workers` and `trainer.pin_memory`.
+- Gradient accumulation is respected even for partial micro-batch sets, so you can safely mix different batch counts.
+For long-running jobs consider exporting the notebook to a script (`jupyter nbconvert --to script`) or reusing the same logic inside a CLI tool.
+
+## Preparing Models
+Download the demo models hosted on Hugging Face:
+```bash
+mini-transformer-fetch AlaBoussoffara/transformer_test
+mini-transformer-fetch AlaBoussoffara/transformer_small
+```
+Use `--name` to customise the local directory and `--force` to refresh an existing download.
+The local folder name defaults to `<author>__<repo>` (e.g. `AlaBoussoffara__transformer_small`). The Hugging Face repo is downloaded as a whole, so if the model files live inside a subfolder (for example `transformer_small/small_model_v1/`), move that entire inner folder—the one that already contains `configs/`, `checkpoints/`, and `tokenizer/`—into `trained_models/` so it becomes your model directory. In practice, after fetching `AlaBoussoffara/transformer_small`, move the `transformer_small/small_model_v1/` directory into `trained_models/` and rename it to the directory name you want to use (for example `AlaBoussoffara__transformer_small/`) so that the final layout is `trained_models/<model-name>/configs/...`.
+
+You can also place your own model manually under `trained_models/<model-name>/`:
+```
+trained_models/
+  my-model/
+    configs/
+      config_inference.yaml
+    checkpoints/
+      best.pt
+    tokenizer/
+      tokenizer.json
+```
+Relative paths in `config_inference.yaml` should stay inside the model folder. Set `MINI_TRANSFORMER_MODELS=/path/to/trained_models` if you store models elsewhere.
+
+## CLI Usage
+Install the optional extras (see Installation) and use the commands below.
+
+```bash
+mini-transformer-infer --model AlaBoussoffara__transformer_small -t "Once upon a time"
+mini-transformer-serve --model AlaBoussoffara__transformer_small --reload
+mini-transformer-ui --model AlaBoussoffara__transformer_small --host 0.0.0.0 --port 8000
+```
+If you see “Tokenizer file not found”, update the model config or set `MINI_TRANSFORMER_TOKENIZER_PATH` to the correct JSON file.
+
+## Chainlit Demo
+Follow these steps to spin up the bundled Chainlit chat UI for a local inference demo.
+
+1. Install the project with the server extras (or run `make create-env`):
+   ```bash
+   pip install -e .[server]
+   ```
+2. Download a demo checkpoint (skip if you already have one under `trained_models/`):
+   ```bash
+   mini-transformer-fetch AlaBoussoffara/transformer_small
+   ```
+3. Launch the Chainlit UI, pointing to the model folder you want to use (defaults to the first available model):
+   ```bash
+   mini-transformer-ui --model AlaBoussoffara__transformer_small --host 0.0.0.0 --port 8000
+   ```
+4. Open http://localhost:8000 in your browser, send a prompt, and use `/model` in chat to switch between downloaded checkpoints.
+   Use `/config temperature=0.7 top_k=50` (or `/config reset`) to tweak generation settings on the fly.
+
+### Environment Variables
+- `MINI_TRANSFORMER_MODELS` – override the models root directory.
+- `MINI_TRANSFORMER_MODEL_NAME` – preselect a model for the server/UI.
+- `MINI_TRANSFORMER_CONFIG_DIR` / `MINI_TRANSFORMER_CONFIG_NAME` – point to custom Hydra configs.
+- `MINI_TRANSFORMER_UI_HOST` / `MINI_TRANSFORMER_UI_PORT` – defaults for Chainlit binding.
+- Optional overrides: `MINI_TRANSFORMER_CHECKPOINT_BEST`, `MINI_TRANSFORMER_TOKENIZER_PATH`, `MINI_TRANSFORMER_OUTPUT_DIR`, etc.
+
+## Docker Inference UI
+Build the lean inference image and launch the Chainlit UI in a container:
+```bash
+make docker-build-infer
+make docker-run-infer  # press Ctrl+C to stop
+```
+Models stay outside the container under `trained_models/`, mounted at runtime with docker compose.
+
+## Programmatic Inference
+```python
+from mini_transformer.model_loader import compose_model_config
+from mini_transformer.inference import run_inference
+
+cfg = compose_model_config("AlaBoussoffara__transformer_small")
+cfg.input_text = "Hello world"
+print(run_inference(cfg)[0])
+```
+
+## Development Quickstart
+```bash
+make create-env
+make lint
+make type
+make test
+pre-commit run --all-files   # optional: run all hooks locally
+```
+
+## Testing & QA
+- Unit tests live under `tests/units/`; run them with `make test` or `python -m pytest`.
+- The suite covers core building blocks (attention math, masking, sampling), CLI flows, and attention-debug utilities—including both pre- and post-layernorm configurations.
+- Add tests alongside new features; keeping coverage high ensures `mini-transformer` behaves the same whether it runs from the repo or as an installed package.
+
+## Makefile Shortcuts
+```bash
+make help          # list common tasks
+make create-env    # create/update the conda env and install extras
+make lint          # format + lint (ruff + black)
+make lint-check    # lint without auto-fixes
+make fmt           # format code
+make precommit     # run the configured pre-commit hooks (auto-fixes where possible)
+make type          # mypy
+make test          # pytest
+make cov           # pytest with coverage
+make fetch-test    # download AlaBoussoffara/transformer_test
+make fetch-small   # download AlaBoussoffara/transformer_small
+make infer         # quick demo inference
+make serve         # run FastAPI server (reload mode)
+make ui            # launch Chainlit UI
+make docker-build-dev   # build the development container
+make docker-run-dev     # open an interactive shell in the development container
+make docker-build-infer # build the inference/UI container
+make docker-run-infer   # run the inference service (Ctrl+C to stop)
+```
+
+## Full Workflow At A Glance
+1. Fetch a model: `mini-transformer-fetch AlaBoussoffara/transformer_small`
+2. Run inference: `mini-transformer-infer --model AlaBoussoffara__transformer_small -t "Once upon a time"`
+3. Launch FastAPI (optional): `mini-transformer-serve --model AlaBoussoffara__transformer_small --reload`
+4. Start Chainlit UI (optional): `mini-transformer-ui --model AlaBoussoffara__transformer_small --host 0.0.0.0 --port 8000`
+
+Environment variables (`MINI_TRANSFORMER_MODELS`, `MINI_TRANSFORMER_MODEL_NAME`, etc.) let you tailor the workflow to your setup.

README.project.md

@@ -1,155 +0,0 @@
-# Mini-Transformer
-
-A compact, encoder–decoder Transformer packaged so it can be used both as a Python library and as a ready-to-run demo. The repository mirrors the installable package layout so cloning the repo or `pip install mini-transformer` gives the same structure and tooling.
-
-## Highlights
-- Typed, unit-tested implementation of an encoder–decoder Transformer with reusable building blocks (`mini_transformer/modules`).
-- Hydra configuration system with both packaged defaults (`mini_transformer/conf`) and editable configs in the repo.
-- Ready-made UIs: FastAPI REST server and Chainlit chat interface.
-- CLI convenience commands for inference, serving, UI launch, and Hugging Face model downloads.
-- Makefile shortcuts, notebooks, and Docker dev environment for day-to-day work.
-
-## Installation
-```bash
-# inside the repository (editable install with optional extras)
-pip install -e .[server,viz]
-```
-Or install the published package:
-```bash
-pip install "mini-transformer[server,viz]"
-```
-
-## Repository Layout
-- `src/mini_transformer/` – installable package (model code, CLI, apps, packaged Hydra configs).
-- `configs/` – editable Hydra configs for local experiments.
-- `trained_models/` – place downloaded or exported checkpoints here (see below).
-- `notebooks/` – exploratory notebooks (`train.ipynb`, `tokenizer.ipynb`, etc.).
-- `tests/` – unit and smoke tests.
-- Supporting files: `pyproject.toml`, `Makefile`, `Dockerfile.dev`, `environment.yml`, etc.
-
-## Training Notebook
-`notebooks/train.ipynb` demonstrates the Hydra-driven training loop used during development.
-- All hyper-parameters come from the composed config (see `configs/train_mode.yaml`); the key knobs live under `trainer.*`.
-- Checkpoint cadence is controlled by `trainer.save_interval` (in optimizer steps) and always saves on epoch boundaries.
-- Dataloader behaviour (workers, pinned memory) can be tuned via `trainer.num_workers` and `trainer.pin_memory`.
-- Gradient accumulation is respected even for partial micro-batch sets, so you can safely mix different batch counts.
-For long-running jobs consider exporting the notebook to a script (`jupyter nbconvert --to script`) or reusing the same logic inside a CLI tool.
-
-## Preparing Models
-Download the demo models hosted on Hugging Face:
-```bash
-mini-transformer-fetch AlaBoussoffara/transformer_test
-mini-transformer-fetch AlaBoussoffara/transformer_small
-```
-Use `--name` to customise the local directory and `--force` to refresh an existing download.
-The local folder name defaults to `<author>__<repo>` (e.g. `AlaBoussoffara__transformer_small`). The Hugging Face repo is downloaded as a whole, so if the model files live inside a subfolder (for example `transformer_small/small_model_v1/`), move that entire inner folder—the one that already contains `configs/`, `checkpoints/`, and `tokenizer/`—into `trained_models/` so it becomes your model directory. In practice, after fetching `AlaBoussoffara/transformer_small`, move the `transformer_small/small_model_v1/` directory into `trained_models/` and rename it to the directory name you want to use (for example `AlaBoussoffara__transformer_small/`) so that the final layout is `trained_models/<model-name>/configs/...`.
-
-You can also place your own model manually under `trained_models/<model-name>/`:
-```
-trained_models/
-  my-model/
-    configs/
-      config_inference.yaml
-    checkpoints/
-      best.pt
-    tokenizer/
-      tokenizer.json
-```
-Relative paths in `config_inference.yaml` should stay inside the model folder. Set `MINI_TRANSFORMER_MODELS=/path/to/trained_models` if you store models elsewhere.
-
-## CLI Usage
-Install the optional extras (see Installation) and use the commands below.
-
-```bash
-mini-transformer-infer --model AlaBoussoffara__transformer_small -t "Once upon a time"
-mini-transformer-serve --model AlaBoussoffara__transformer_small --reload
-mini-transformer-ui --model AlaBoussoffara__transformer_small --host 0.0.0.0 --port 8000
-```
-If you see “Tokenizer file not found”, update the model config or set `MINI_TRANSFORMER_TOKENIZER_PATH` to the correct JSON file.
-
-## Chainlit Demo
-Follow these steps to spin up the bundled Chainlit chat UI for a local inference demo.
-
-1. Install the project with the server extras (or run `make create-env`):
-   ```bash
-   pip install -e .[server]
-   ```
-2. Download a demo checkpoint (skip if you already have one under `trained_models/`):
-   ```bash
-   mini-transformer-fetch AlaBoussoffara/transformer_small
-   ```
-3. Launch the Chainlit UI, pointing to the model folder you want to use (defaults to the first available model):
-   ```bash
-   mini-transformer-ui --model AlaBoussoffara__transformer_small --host 0.0.0.0 --port 8000
-   ```
-4. Open http://localhost:8000 in your browser, send a prompt, and use `/model` in chat to switch between downloaded checkpoints.
-   Use `/config temperature=0.7 top_k=50` (or `/config reset`) to tweak generation settings on the fly.
-
-### Environment Variables
-- `MINI_TRANSFORMER_MODELS` – override the models root directory.
-- `MINI_TRANSFORMER_MODEL_NAME` – preselect a model for the server/UI.
-- `MINI_TRANSFORMER_CONFIG_DIR` / `MINI_TRANSFORMER_CONFIG_NAME` – point to custom Hydra configs.
-- `MINI_TRANSFORMER_UI_HOST` / `MINI_TRANSFORMER_UI_PORT` – defaults for Chainlit binding.
-- Optional overrides: `MINI_TRANSFORMER_CHECKPOINT_BEST`, `MINI_TRANSFORMER_TOKENIZER_PATH`, `MINI_TRANSFORMER_OUTPUT_DIR`, etc.
-
-## Docker Inference UI
-Build the lean inference image and launch the Chainlit UI in a container:
-```bash
-make docker-build-infer
-make docker-run-infer  # press Ctrl+C to stop
-```
-Models stay outside the container under `trained_models/`, mounted at runtime with docker compose.
-
-## Programmatic Inference
-```python
-from mini_transformer.model_loader import compose_model_config
-from mini_transformer.inference import run_inference
-
-cfg = compose_model_config("AlaBoussoffara__transformer_small")
-cfg.input_text = "Hello world"
-print(run_inference(cfg)[0])
-```
-
-## Development Quickstart
-```bash
-make create-env
-make lint
-make type
-make test
-pre-commit run --all-files   # optional: run all hooks locally
-```
-
-## Testing & QA
-- Unit tests live under `tests/units/`; run them with `make test` or `python -m pytest`.
-- The suite covers core building blocks (attention math, masking, sampling), CLI flows, and attention-debug utilities—including both pre- and post-layernorm configurations.
-- Add tests alongside new features; keeping coverage high ensures `mini-transformer` behaves the same whether it runs from the repo or as an installed package.
-
-## Makefile Shortcuts
-```bash
-make help          # list common tasks
-make create-env    # create/update the conda env and install extras
-make lint          # format + lint (ruff + black)
-make lint-check    # lint without auto-fixes
-make fmt           # format code
-make precommit     # run the configured pre-commit hooks (auto-fixes where possible)
-make type          # mypy
-make test          # pytest
-make cov           # pytest with coverage
-make fetch-test    # download AlaBoussoffara/transformer_test
-make fetch-small   # download AlaBoussoffara/transformer_small
-make infer         # quick demo inference
-make serve         # run FastAPI server (reload mode)
-make ui            # launch Chainlit UI
-make docker-build-dev   # build the development container
-make docker-run-dev     # open an interactive shell in the development container
-make docker-build-infer # build the inference/UI container
-make docker-run-infer   # run the inference service (Ctrl+C to stop)
-```
-
-## Full Workflow At A Glance
-1. Fetch a model: `mini-transformer-fetch AlaBoussoffara/transformer_small`
-2. Run inference: `mini-transformer-infer --model AlaBoussoffara__transformer_small -t "Once upon a time"`
-3. Launch FastAPI (optional): `mini-transformer-serve --model AlaBoussoffara__transformer_small --reload`
-4. Start Chainlit UI (optional): `mini-transformer-ui --model AlaBoussoffara__transformer_small --host 0.0.0.0 --port 8000`
-
-Environment variables (`MINI_TRANSFORMER_MODELS`, `MINI_TRANSFORMER_MODEL_NAME`, etc.) let you tailor the workflow to your setup.