README.md

---
title: Agentic_A-Maze_Studio
app_file: app.py
sdk: gradio
sdk_version: 6.14.0
---
# Multilingual A-Maze Task Enhanced by LLM Agent


This project is a multilingual version of the A-Maze Task, enhanced by an LLM agent. It generates multiple distractors for each word in a sentence using an LLM and a lexicon or multiple LLMs. It produces JSON outputs that can be parsed to build maze tasks.

## Quick start
1. Edit `config.yaml` (usually just `LANGUAGE_CODE`, `MODEL_ID`, and `PROCESSING_MODE`).
2. Run `api/llm_agent.py` for local Hugging Face models.
3. Run `api/chat_agent.py` for OpenAI chat models.

### Auto path resolution
If `LEXICON_PATH`, `INPUT_DATA_PATH`, `TEMPLATE_DIR`, or `OUTPUT_PATH` are empty in `config.yaml`,
the app resolves them automatically from `LANGUAGE_CODE`:

- Lexicon: `data/lexicon/lexicon_{language_code}.txt`
- Input (`naturalistic_reading`): `data/input/{language_code}/naturalistic_{language_code}.txt`
- Input (`controlled_experiment`): `data/input/{language_code}/controlled_{language_code}.txt`
- Template dir: `template/{language_code}`
- Output: `results/{language_code}/{agent}_out_{lang}_{model}.json`

You can still override paths from CLI (`--input-data-path`, `--lexicon-path`, `--template-dir`, `--output-path`).

## Web app
Run a browser UI for sentence/file input, settings, JSON preview, and download:

```bash
python web_app.py --share
```

- `--share` creates a public Gradio link.
- Without `--share`, open the local URL (default `http://0.0.0.0:7860`).

## Free public hosting (Hugging Face Spaces)
You can deploy the app for free and share a stable URL:

```bash
gradio deploy --provider spaces --app-file app.py --title "Agentic A-Maze Studio"
```

After deployment:
- Your Space URL stays stable.
- When you push code updates to the Space repo, the app rebuilds and the same URL shows the new version.

Notes:
- `app.py` is the Spaces entrypoint and serves `web_app.build_app()`.
- `requirements.txt` is used by Spaces for dependency install.