Azathoth UI

A local editor for Azathoth workflows, served on your own computer and opened in your browser.

The editor keeps an Azathoth instance of its own, and drives it only through Azathoth's public service API, azathoth.api, and needs Azathoth 1.4.

Installing it

Install it into a venv of its own, as Installing Azathoth shows for Azathoth, with Python 3.11 or newer:

python -m pip install azathoth-ui

pip brings Azathoth 1.4 with it, from PyPI.

Running it

azathoth-ui

The command creates the editor's own Azathoth instance the first time, serves the editor on 127.0.0.1, and opens it in your browser. It prints the address it opened, with a key for this launch; only a browser that has opened that address can use the editor. Press Ctrl+C to stop it.

• --database edits another Azathoth database, an SQLite file or a PostgreSQL URL. AZATHOTH_DATABASE does the same.
• --port listens on one port rather than any free one.
• --no-browser prints the address without opening it.

Providers are configured as they are for Azathoth's own command line, through the environment: set OPENROUTER_API_KEY, or AZATHOTH_BEDROCK=1 with your AWS credentials, before launching it. The Models page then lists what they serve, and keeps the editor's local portfolio, the models its workflows may use; a shared server keeps its own (ADR 0006). A workflow's Run button runs it on text, JSON or a file, a PDF, an image or text, and shows the run as it goes: each step lit on the graph as it starts and ends, every event in words, and how it ended. A run goes on if you leave its page, and the editor's rail points to the runs still running. Every run is kept and listed on its workflow's page, with what each step did. While you edit, the editor asks Azathoth what it would refuse and whether the workflow could run here, and a step's details try that one step alone, on the values you give its inputs, keeping nothing (ADR 0007). The Remotes page names the shared instances your workflows ship to, each with the environment variable its token is read from; set it before launching the editor, which never sees the token itself. A remote's page says where everything stands there, and pulls what it holds that you lack. Ship, on every workflow, tool and benchmark, pushes it to a remote after saying where it stands, and reports Azathoth's warnings of what would stop it running there (ADR 0008). ADR 0001 explains how the server keeps other sites and other users out.

Development

The editor is built against released Azathoth from PyPI: make install takes the release pyproject.toml requires, and never Azathoth's own checkout.

The web app needs Node ^20.19.0 || >=22.12.0, and npm.

python -m venv .venv
source .venv/bin/activate
make install
make install-web
make build-web
make check

make build-web builds the web app into the package, where azathoth-ui serves it. make check lints, type-checks and tests both halves: the Python package, and the web app with ESLint, Prettier, TypeScript and Vitest. It never runs Azathoth's own test suite.

make wheel builds the web app, then the wheel with it, into dist/. Building a wheel refuses until the web app is built.

To work on the web app with hot reloading, start the server on a fixed port, open the address it prints once, then start Vite and open http://127.0.0.1:5173:

azathoth-ui --port 8765 --no-browser
cd web && npm run dev

License

MIT. See LICENSE.