pyproject.toml, which is committed and shared by every checkout of the
project, and fxtr.local.toml, which says where this machine reaches the project’s database and
is never committed.
fxtr finds a project by walking up to the nearest pyproject.toml: from a launcher, starting at
the path it passes as its anchor (usually its own __file__), and from the fxtr command, at the
working directory (or --project). That file must have a [tool.fxtr] table; if it doesn’t, fxtr
reports an error rather than looking further up.
What fxtr new writes
uvx fxtr new DIRECTORY writes a project into a new or empty directory (from a project that
already depends on fxtr, uv run fxtr new does the same):
- The project is named after the directory, unless
--namegives another name:My_Projectis the projectmy-project, whose code is the packagemy_project. - It depends on the fxtr that ran
fxtr new, or a later version. - A new project has no experiment or launcher, and its
[tool.fxtr] moduleslist is empty.--exampleadds a greeting experiment insrc/<package>/experiment.py(an entity type, a step, and a workflow), registers that module, and addslaunch.py, which runs it. It also adds renderers for the greeting and a results overview of the workflow,views/src/overview.tsx. views/has its own pnpm workspace boundary, lockfile, and installation, so installing its dependencies never changes a workspace the project sits in.- It runs
git init, unless the directory is already in a git or jj checkout, and prints the next steps. Runuv syncin the project to install its dependencies and write the virtual environment anduv.lock.
pyproject.toml
The file fxtr new writes, without its comments:
pyproject.toml
The modules whose import registers the project’s steps and workflows. A process with no script
of its own imports them: a resumed job,
fxtr run, and the viewer. Add each experiment module
you write to this list. A step or workflow that no listed module registers can still run in a
job launched by a script that imports it, but that job can’t be resumed, fxtr run can’t find
the workflow, and the viewer can’t link its cards to the code.How long a job’s lease may go without a heartbeat before fxtr presumes the process running it
is gone, and a resume may take the job over. Every process of a project must agree on it.
The directory of the project’s renderer package, relative to the project root. Without this
table the project has no renderers of its own, and the viewer uses its defaults.
package = trueinstalls the project into its own virtual environment, so that thefxtrcommand, which has no project directory on its import path, can import the modules in[tool.fxtr] modules. Keep the definitions undersrc/<package>/and launcher scripts at the project root.- The
runnerextra is the Postgres runner, anddebug-webis the viewer thatfxtr viewserves.
uv.lock, so commit uv.lock whenever the dependencies change (uv add and
uv sync update both).
fxtr.local.toml
uv run fxtr init --database-url URL writes this file and creates the project’s tables:
fxtr.local.toml
A SQLAlchemy
postgresql+asyncpg://... URL for the project’s Postgres server. Required unless
the FXTR_DATABASE_URL environment variable is set, which overrides it.The Postgres schema the project’s tables live in: lowercase letters, digits, and
_, not
starting with a digit, and at most 63 characters. By default it is fxtr_ followed by the
project’s name, lowercased, with every character other than a letter, digit, or _ replaced by
_. fxtr init --schema writes another.fxtr init --force replaces an existing file. Everything the project stores lives in its schema:
jobs, project arrays, entities, and the step cache. Resuming or viewing a job therefore needs the
configuration that launched it. The project’s client creates the tables when they are missing, but
it doesn’t start the server or create the database. To keep trial runs apart from real results,
point the project at a scratch schema while experimenting (see
Before you launch).
fxtr reads both files strictly: a setting it doesn’t know, or a value of the wrong type, is an
error, so a misspelled setting is never silently ignored.
.env
.env holds the API keys of the model providers your experiments
call. fxtr new writes one with empty placeholders:
.env
.env override variables set in the environment.