# uproot

> Documentation for uproot, a modern framework for browser-based behavioral experiments

uproot is a modern, open-source Python framework for developing and conducting browser-based behavioral experiments (surveys, games, real-time multiplayer interactions). Experiments are Python packages: pages are classes, templates are Jinja2, and all data goes into an append-only log.

Notes for agents:

- Every page below is available as clean Markdown: append `.md` to the page path (e.g., https://uproot.science/building/forms.md). `llms-full.txt` contains all pages in one file.
- uproot app modules get everything via `from uproot.smithereens import *`; no manual imports are needed in examples.
- Complete working experiments: https://github.com/mrpg/uproot-examples (branch `main`). Framework source: https://github.com/mrpg/uproot. Documentation source: https://github.com/mrpg/uproot-docs.
- An agent skill with condensed API knowledge: https://github.com/mrpg/uproot-skill
- To try an experiment locally, run `uproot start --simulate` inside a project.

## Overview

- [Home](https://uproot.science/index.md): Overview of uproot, an open-source Python framework for browser-based behavioral experiments, with a quick example and links to get started.
- [Why uproot?](https://uproot.science/why-uproot.md): Why researchers choose uproot: append-only data, exact reproducibility, tamper resistance, real-time interaction, and flexible page orders.
- [Getting help](https://uproot.science/help.md): Where to get help with uproot: the documentation, coding agents, email, and GitHub issues.
- [Legal information](https://uproot.science/legal.md): Who made uproot, its license, warranty disclaimer, and contact details.

## Getting started

- [Installation](https://uproot.science/getting-started/installation.md): Install uproot with uv, create a project, run the server, open the admin interface, and set up AI-assisted development.
- [Tutorial: A complete experiment](https://uproot.science/getting-started/tutorial.md): Step-by-step tutorial that builds a complete two-player prisoner’s dilemma with pages, forms, groups, and synchronization.
- [Project structure](https://uproot.science/getting-started/project-structure.md): Layout of an uproot project: main.py, app modules, templates, _static files, the database, and environment variables.
- [Upgrading](https://uproot.science/upgrade.md): Upgrade uproot to a new release while keeping an exact version pin so your study stays reproducible.

## Building experiments

- [Pages and templates](https://uproot.science/building/pages.md): Define pages as Python classes, write Jinja2 or Markdown templates, pass variables, show pages conditionally, and use NoshowPage and lifecycle methods.
- [Collecting data with forms](https://uproot.science/building/forms.md): Collect participant responses with form fields: the fields dictionary, field types and options, rendering, validation, dynamic fields, and stealth fields.
- [Storing and accessing data](https://uproot.science/building/data.md): How uproot stores data in an append-only log: player, group, and session data, initialization callbacks, random numbers, mutable values, and accessing other players.
- [Displaying results](https://uproot.science/building/results.md): Show participants their outcomes and payoffs with Jinja2: other players’ data, number formatting, calculations, history tables, and filters.
- [SmoothOperators](https://uproot.science/building/operators.md): SmoothOperators control the page order: RandomOrder, Bracket, Rounds, Repeat, and Between for randomization, repetition, and between-subjects designs.
- [Live methods](https://uproot.science/building/live-methods.md): Call Python from JavaScript without reloading the page using the @live decorator and uproot.invoke, with examples for validation, counters, and real-effort tasks.
- [Using Alpine.js](https://uproot.science/building/alpinejs.md): Add interactivity to templates with the built-in Alpine.js: essentials, global stores, constants in JavaScript, and combining Alpine with live methods.

## Multiplayer experiments

- [Grouping participants](https://uproot.science/multiplayer/groups.md): Form groups with GroupCreatingWait, assign roles with after_grouping, access group members, store group data, and create groups manually.
- [Synchronizing progress](https://uproot.science/multiplayer/synchronization.md): Wait for all group members with SynchronizingWait, compute payoffs in all_here, synchronize sessions, and handle repeated games.
- [Real-time interactions](https://uproot.science/multiplayer/real-time.md): Push real-time updates between participants with notify, send_to, and spawn, with examples for live observation, drawing, and markets.
- [Built-in chat](https://uproot.science/multiplayer/chat.md): Add the built-in chat to session- or group-level experiments, display it in templates, react to messages, and style it.

## Advanced features

- [Page timeouts](https://uproot.science/advanced/timeouts.md): Advance participants automatically with static or dynamic page timeouts, handle expiration, span timeouts across pages, and customize the countdown.
- [Handling dropouts](https://uproot.science/advanced/dropouts.md): Detect participants who disconnect with watch_for_dropout, mark dropouts manually, and keep group experiments running.
- [File uploads](https://uproot.science/advanced/uploads.md): Accept file uploads with FileField, validate them, and store them yourself via stealth fields.
- [Custom data models](https://uproot.science/advanced/models.md): Store ordered, append-only collections such as bids or transaction logs with custom data models and Entry types.
- [Custom settings forms](https://uproot.science/advanced/settings-forms.md): Replace the raw JSON session settings editor in the admin interface with a custom HTML form for your app.

## Running experiments

- [The admin interface](https://uproot.science/running/admin.md): Use the admin interface to create sessions, monitor and manage participants, chat with them, test apps with simulated responses, and back up the database.
- [Sessions and rooms](https://uproot.science/running/rooms.md): Sessions and rooms: how participants join an experiment, room labels and capacity, and configuring default rooms.
- [Running on Prolific](https://uproot.science/running/prolific.md): Run an uproot study on Prolific: create a room, give Prolific the study URL, send completion codes, and handle bonuses and screen-outs.
- [Exporting data](https://uproot.science/running/export.md): Download your data as a ZIP briefcase and analyze it in R or Python: the ultralong, sparse, and latest formats, columns, filters, and page times.
- [Advanced data access](https://uproot.science/running/export-advanced.md): Export data programmatically via the REST API and JSONL streams, back up the database with dumps, and analyze offline with uproot.read.
- [Deployment](https://uproot.science/running/deployment.md): Make your experiment reachable over the internet with Cloudflare, your own VPS, or a hosting service.
- [VPS setup](https://uproot.science/running/vps-setup.md): Deploy uproot on a fresh VPS step by step: SSH hardening, system packages, project setup, nginx, and HTTPS.

## Reference

- [Form fields](https://uproot.science/reference/fields.md): Reference for every uproot form field type and its parameters.
- [Page methods](https://uproot.science/reference/page-methods.md): Reference for all page methods in lifecycle order, page class attributes, and wait page callbacks.
- [API reference](https://uproot.science/reference/api.md): Reference for uproot’s Python API: page types, SmoothOperators, PlayerContext, real-time, dropout, and group functions, live methods, and StorageBunch.
- [Admin REST API](https://uproot.science/reference/admin-api.md): Reference for the Admin REST API under /admin/api/v1/: authentication, sessions, players, admin chat, data export, rooms, and system endpoints.
- [CLI commands](https://uproot.science/reference/cli.md): Reference for uproot’s command-line interface: global commands and project commands such as run, start, reset, dump, and new.

## Optional

- [Full documentation in one file](https://uproot.science/llms-full.txt): every page above, concatenated in navigation order