README.md

metadata

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:

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:

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.