Metadata-Version: 2.4
Name: azathoth-ui
Version: 1.4.0
Summary: A local editor for Azathoth workflows, served in your browser.
Author: Eris Discordia Montano
License: MIT
Project-URL: Homepage, https://github.com/EldritchInc/azathoth-ui
Project-URL: Repository, https://github.com/EldritchInc/azathoth-ui
Keywords: artificial-intelligence,llm,workflow-editor,azathoth
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: azathoth-ai==1.4.*
Requires-Dist: starlette>=0.40
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: setuptools>=68; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Dynamic: license-file

# Azathoth UI

A local editor for [Azathoth](https://github.com/EldritchInc/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](https://github.com/EldritchInc/azathoth/blob/main/docs/install.md)
shows for Azathoth, with Python 3.11 or newer:

```bash
python -m pip install azathoth-ui
```

pip brings Azathoth 1.4 with it, from PyPI.

## Running it

```bash
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](https://github.com/EldritchInc/azathoth-ui/blob/main/docs/adrs/0006-local-models-and-the-portfolio.md)).
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](https://github.com/EldritchInc/azathoth-ui/blob/main/docs/adrs/0007-running-and-watching-workflows.md)).
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](https://github.com/EldritchInc/azathoth-ui/blob/main/docs/adrs/0008-shipping-to-a-remote.md)).
[ADR 0001](https://github.com/EldritchInc/azathoth-ui/blob/main/docs/adrs/0001-local-server-security.md) 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.

```bash
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>:

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

## License

MIT. See [LICENSE](https://github.com/EldritchInc/azathoth-ui/blob/main/LICENSE).
