Repository navigation
Releases
Azathoth 1.4.0
Azathoth 1.4.0b1
azathoth.api, a public service API that the command line, azathoth-mcp
and the coming local editor all call. It browses and imports workflows,
tools and benchmarks, lists the models providers serve, keeps the model
portfolio, initializes databases, and runs and invokes workflows,
reporting each step and context change to a callback as it happens and
stopping when cancelled. It returns its own
frozen models, each with its equivalentazathothcommand, raises errors
with stable codes, and is provisional until 1.4.0
(ADR 0120).- azathoth-mcp runs each tool call through the service API. A call now asks
the providers what they serve, asazathoth job rundoes, rather than
once while production stays the same, so a model authorized or a tool
imported reaches a running server at once; a call the client cancels
cancels its invocation, which the same call under its key resumes
(ADR 0120). azathoth.apiruns and invokes a workflow on a file:RunFileholds a
document or an image, JSON or text, checked and kept as--input-file
keeps one, and refused before anything runs when it is not its media type
(ADR 0121).azathoth.apichecks a workflow document without saving it, naming every
problem with where it is and its step; says, step by step, whether a
document could run here now and on which models; and lists the
portfolio's models that meet a step's requirements, by the rules a run
uses
(ADR 0121).azathoth.apireads back the runs an instance kept: a workflow's runs
newest first, and one run with its input, its result, and each step's
output, values, measurements and failed attempts
(ADR 0121).azathoth.apitries one step of a workflow document alone, on the inputs
given, a file among them, reporting its events as a run does and keeping
no run
(ADR 0121).- Every workflow, tool and benchmark revision records its lineage: a
revision digest that covers its content and every revision before it, the
revision it was built on, and who imported it. Every portfolio entry
records its digest, who authorized it and when. The database schema is now
version 3; runazathoth initonce to upgrade a PostgreSQL database, which
records the lineage it already holds. An SQLite file is upgraded when it is
opened
(ADR 0122). - Importing a document identical to the latest revision appends nothing and
says so:Workflow <WORKFLOW_ID> is unchanged at revision <NUMBER>., and
likewise for tools and benchmarks. Before, it appended a duplicate
revision. Importing an earlier revision's document still appends a revert
(ADR 0122). - Who imports is
AZATHOTH_AUTHOR, asName <email>orName, or else the
operating system's username; a malformedAZATHOTH_AUTHORstops the
import, authorizing a model, and adding a benchmark case. The standard
tools are recorded as Azathoth's
(ADR 0122). workflow showandbenchmark showname each revision's digest, parent
and author, and history lines end with who imported each revision when
that is known
(ADR 0122).azathoth.apireports each revision's revision digest, parent and author,
and each portfolio entry's digest, author and time. Imports take
based_on, building on an earlier revision to fork, and return
WorkflowImport,ToolImportandBenchmarkImport, which say whether a
revision was created;api.opentakes theauthorto record
(ADR 0122).- Sensitivity labels: a run's input, a job's input and a benchmark case may
be labelledpublic,internalorrestricted, with--sensitivity,
an input source'ssensitivityor the service API'ssensitivity=.
Unlabelled data is internal and unchanged. A child workflow and a case
made from a run are never less sensitive than their source, and a
benchmark is as sensitive as its most sensitive case
(ADR 0123). - Each portfolio model declares what its provider does with data:
model authorize --no-retention --no-training, ormodel policyat any
time, which also shows who declared it and when. The database schema is
now version 4; runazathoth initonce to upgrade a PostgreSQL database
(ADR 0123). - Restricted input reaches only models declared to neither retain nor train
on data. A context prompt step that would send it anywhere else sends
nothing and says which model and what to declare, and a production
invocation's caller is told the same. Steps that choose a model, and
production with approved substitutes, choose a private one first;
semantic judges and the optimizer's substitutes of restricted cases must
be private; readiness and model matching take a label
(ADR 0123). - azathoth-mcp: an exposure document's tool may take
"sensitivity": "restricted", the operator's declaration that its client may hold
restricted data. Its calls are restricted, andget_invocationreturns no
restricted invocation through a tool not so exposed
(ADR 0123). - Labels are shown wherever data is: the API's run, invocation and
benchmark views, aSensitivity:line in show commands for data that is
not internal, a warning on standard error from every command that prints
restricted data, and theazathoth.sensitivityspan attribute. Tools are
not gated by labels in 1.4
(ADR 0123). - A remote:
azathoth remote serveserves an instance's workflows, tools
and benchmarks over HTTP, for other instances to push to and pull from,
with the newremoteextra.azathoth remote pushandpull, and the
service API'sinstance.remote(url), send each document's latest
revision, the revisions it was reached by, and the tool versions, child
workflows and benchmark content it needs, sending only what the other
side lacks. Production state, the portfolio and runs never travel
(ADR 0124). - Revision digests are a revision's identity everywhere; each instance
numbers what it saves. A remote moves only forward: a push whose lineage
diverged there is refused, and a pull forks a lineage that diverged here
on the revision its pulled revisions build on, so nothing is lost
(ADR 0124). - A remote's owner issues bearer tokens with
azathoth remote token create,
shown once and kept only as digests;listandrevokemanage them, and
a client reads its token fromAZATHOTH_REMOTE_TOKEN. The database schema
is now version 5; runazathoth initonce to upgrade a PostgreSQL
database
(ADR 0124). - A remote refuses restricted data unless it is served with
--accept-restricted, and a pull brings restricted benchmarks only with
--include-restricted
(ADR 0124). - A remote's authentication, policy and audit are seams a plugin fills,
through theazathoth.remoteentry-point group; the core's let only the
owner in and audit nothing. A remote's capabilities name its protocol,
versions, edition and plugins, and a client refuses another protocol
before sending anything
(ADR 0124). azathoth.api'smodels.matching(..., scope="catalog")matches every
model the providers serve, marked authorized or not, for a pulled
workflow's steps. The container image includes theremoteextra
(ADR 0124).azathoth.api'sremote.status()compares this instance with a remote:
each workflow, tool version and benchmark is in sync, ahead, behind,
diverged, or held by one side only, a workflow names the revision in
production at the remote, and each model says whether it is authorized
here and there. A remote that cannot be reached is no error: its side is
unknown, and its models are read from the portfolio last read from it
(ADR 0125).- A remote answers
/v1/heads,/v1/portfolioand/v1/credentials,
read-only, under a newread_portfolioaction andportfolio_readaudit
event. The credential check is asked by name, and never returns a value
(ADR 0125). azathoth remote pushwa...
Azathoth 1.4.0a3
azathoth.api, a public service API that the command line, azathoth-mcp
and the coming local editor all call. It browses and imports workflows,
tools and benchmarks, lists the models providers serve, keeps the model
portfolio, initializes databases, and runs and invokes workflows,
reporting each step and context change to a callback as it happens and
stopping when cancelled. It returns its own
frozen models, each with its equivalentazathothcommand, raises errors
with stable codes, and is provisional until 1.4.0
(ADR 0120).- azathoth-mcp runs each tool call through the service API. A call now asks
the providers what they serve, asazathoth job rundoes, rather than
once while production stays the same, so a model authorized or a tool
imported reaches a running server at once; a call the client cancels
cancels its invocation, which the same call under its key resumes
(ADR 0120). azathoth.apiruns and invokes a workflow on a file:RunFileholds a
document or an image, JSON or text, checked and kept as--input-file
keeps one, and refused before anything runs when it is not its media type
(ADR 0121).azathoth.apichecks a workflow document without saving it, naming every
problem with where it is and its step; says, step by step, whether a
document could run here now and on which models; and lists the
portfolio's models that meet a step's requirements, by the rules a run
uses
(ADR 0121).azathoth.apireads back the runs an instance kept: a workflow's runs
newest first, and one run with its input, its result, and each step's
output, values, measurements and failed attempts
(ADR 0121).azathoth.apitries one step of a workflow document alone, on the inputs
given, a file among them, reporting its events as a run does and keeping
no run
(ADR 0121).- Every workflow, tool and benchmark revision records its lineage: a
revision digest that covers its content and every revision before it, the
revision it was built on, and who imported it. Every portfolio entry
records its digest, who authorized it and when. The database schema is now
version 3; runazathoth initonce to upgrade a PostgreSQL database, which
records the lineage it already holds. An SQLite file is upgraded when it is
opened
(ADR 0122). - Importing a document identical to the latest revision appends nothing and
says so:Workflow <WORKFLOW_ID> is unchanged at revision <NUMBER>., and
likewise for tools and benchmarks. Before, it appended a duplicate
revision. Importing an earlier revision's document still appends a revert
(ADR 0122). - Who imports is
AZATHOTH_AUTHOR, asName <email>orName, or else the
operating system's username; a malformedAZATHOTH_AUTHORstops the
import, authorizing a model, and adding a benchmark case. The standard
tools are recorded as Azathoth's
(ADR 0122). workflow showandbenchmark showname each revision's digest, parent
and author, and history lines end with who imported each revision when
that is known
(ADR 0122).azathoth.apireports each revision's revision digest, parent and author,
and each portfolio entry's digest, author and time. Imports take
based_on, building on an earlier revision to fork, and return
WorkflowImport,ToolImportandBenchmarkImport, which say whether a
revision was created;api.opentakes theauthorto record
(ADR 0122).
Azathoth 1.4.0a2
azathoth.api, a public service API that the command line, azathoth-mcp
and the coming local editor all call. It browses and imports workflows,
tools and benchmarks, lists the models providers serve, keeps the model
portfolio, initializes databases, and runs and invokes workflows,
reporting each step and context change to a callback as it happens and
stopping when cancelled. It returns its own
frozen models, each with its equivalentazathothcommand, raises errors
with stable codes, and is provisional until 1.4.0
(ADR 0120).- azathoth-mcp runs each tool call through the service API. A call now asks
the providers what they serve, asazathoth job rundoes, rather than
once while production stays the same, so a model authorized or a tool
imported reaches a running server at once; a call the client cancels
cancels its invocation, which the same call under its key resumes
(ADR 0120). azathoth.apiruns and invokes a workflow on a file:RunFileholds a
document or an image, JSON or text, checked and kept as--input-file
keeps one, and refused before anything runs when it is not its media type
(ADR 0121).azathoth.apichecks a workflow document without saving it, naming every
problem with where it is and its step; says, step by step, whether a
document could run here now and on which models; and lists the
portfolio's models that meet a step's requirements, by the rules a run
uses
(ADR 0121).azathoth.apireads back the runs an instance kept: a workflow's runs
newest first, and one run with its input, its result, and each step's
output, values, measurements and failed attempts
(ADR 0121).azathoth.apitries one step of a workflow document alone, on the inputs
given, a file among them, reporting its events as a run does and keeping
no run
(ADR 0121).
Azathoth 1.4.0a1
azathoth.api, a public service API that the command line, azathoth-mcp
and the coming local editor all call. It browses and imports workflows,
tools and benchmarks, lists the models providers serve, keeps the model
portfolio, initializes databases, and runs and invokes workflows,
reporting each step and context change to a callback as it happens and
stopping when cancelled. It returns its own
frozen models, each with its equivalentazathothcommand, raises errors
with stable codes, and is provisional until 1.4.0
(ADR 0120).- azathoth-mcp runs each tool call through the service API. A call now asks
the providers what they serve, asazathoth job rundoes, rather than
once while production stays the same, so a model authorized or a tool
imported reaches a running server at once; a call the client cancels
cancels its invocation, which the same call under its key resumes
(ADR 0120).
Azathoth 1.2.0
Azathoth 1.2 serves workflows to AI clients. azathoth-mcp, a new package
released with Azathoth at the same version, offers the promoted workflows an
operator lists as Model Context Protocol tools, to Claude Desktop, IDEs and
agents, locally over stdio or to a team over HTTP behind the organization's
identity provider. Everything 1.1 promised is unchanged: documents, commands,
documented output and the database schema are as they were.
The AWS stack, the worker and the S3 tools are unchanged, and the image only
gained azathoth-mcp, which the stack does not run, so this release was not
deployed to the AWS sandbox again
(Release Validation).
Serving Workflows to AI Clients
azathoth-mcpserves promoted workflows as MCP tools. It is a separate
distribution, released with Azathoth at the same version and requiring its
minor release. Only the workflows an operator lists in an exposure document
are offered, each as one tool, under the name and description written for
it; nothing that changes a workflow is ever offered (ADR 0111).- Every call is a recorded, idempotent invocation of the workflow's
active production revision, run asjob runruns a job request: a repeated
key replays, an interrupted invocation resumes, and the caller is recorded
with it.get_invocationreturns an invocation's input, outcome, caller and
run, step by step (ADR 0111). - Over HTTP it is an OAuth 2.1 resource server. It accepts only signed
tokens from the organization's identity provider, issued for its own URL,
and grants each tool by its own scope; it advertises them in its Protected
Resource Metadata, and never logs a token. Without authorization it listens
only on a loopback address (ADR 0111). - It ships in the container image, and the release publishes both
packages together. Serving Workflows Over MCP covers Claude Desktop, teams and the container
(ADR 0111).
Upgrading From 1.1
Nothing changes for an existing installation. Upgrade, and run azathoth init
as after every upgrade:
python -m pip install --upgrade azathoth-ai
azathoth initpython -m pip install --upgrade azathoth-ai
azathoth initTo serve workflows over MCP, install azathoth-mcp into the same venv. From
then on, upgrade both in one command: each release of it requires its own
minor release of azathoth-ai.
Azathoth 1.1.0
Note: the AWS deployment (Running on AWS) has been checked in two halves: CloudFormation created every resource in the template in a real AWS account, and the released image ran its queue worker, the guide's job, the large-file example and a mid-job stop against an emulator of SQS and S3. A run on Fargate itself will follow; any fix it needs ships as 1.1.1.
Azathoth 1.1 runs in production. Programs send it jobs through a queue,
workers on AWS run them against one PostgreSQL database, and a run cut short
by a deploy or a lost machine resumes where it stopped. Workflows compose from
a standard tool library that ships in the package, map a child over a list,
take their inputs by reference, and process data of any size from S3. Models
run on OpenRouter or Amazon Bedrock, and every run can be traced.
Composing Workflows
- A standard tool library ships in the package, installed by
azathoth init(ADR 0095).
Composing workflows needs no checkout of the repository. - Data-shaping tools pick, build, merge and validate JSON and split, join
and fill in text:json_select,json_object,json_merge,
validate_json,chunk_text,join_textandrender_template. - A step input may be a constant, written in the workflow document
(ADR 0094). - Loops are budgeted from their settings:
loop_workflow1.1.0 takes a
budget_seconds, and every process tool is told its own timeout
(ADR 0093). map_workflowruns a child once per item of a list, several at a
time, and returns the results in order
(ADR 0106).- A child records where it came from: the step and run that started it,
and its root, with nesting bounded by the engine
(ADR 0104).
Inputs and Jobs
- An input is a value or a reference, a
file://ors3://URI with a
media type, resolved before the run starts and kept by its digest
(ADR 0096,
ADR 0108). - A versioned job envelope requests an invocation and reports its result,
with an idempotency key that makes a repeated request replay
(azathoth job run,
ADR 0097). - Data larger than an input may be stays in S3:
split_s3_objectstreams
an object into chunk objects, andread_s3_objectreads one back
(ADR 0110).
Running in Production
- PostgreSQL keeps durable state for many processes at once, selected by
apostgresql://AZATHOTH_DATABASE
(ADR 0102). - Interrupted runs resume from their journal, under a lease one process
holds at a time (azathoth run resume,
ADR 0105). - A container image for amd64 and arm64, with an SBOM and provenance,
signed by the release workflow
(ADR 0101). - Queue workers take job requests from SQS, settle each message by its
result, keep a running job's message hidden, and drain on SIGTERM
(azathoth worker run,
ADR 0107). - One CloudFormation template deploys a fleet of workers on Fargate, with
least-privilege IAM, secrets from Secrets Manager and scaling on the queue
(ADR 0109).
Models and Evidence
- Amazon Bedrock runs models beside OpenRouter, with its own discovery,
IAM policy and prices
(ADR 0103). - OpenTelemetry tracing of every run, step and model call, as an optional
extra (ADR 0100). - A step can report its confidence, recorded with its outputs
(ADR 0098). - The optimizer evaluates its final generation, so a candidate proposed
last is measured before the winner is chosen
(ADR 0091),
andworkflow promote --experimentdeploys an experiment's winner
directly (ADR 0092).
Security
- Process tools see only the environment they declare, beside a small
base set, so a tool never receives a key it did not ask for
(ADR 0099).
Upgrading From 1.0
Upgrade the package, then run init once against each database:
python -m pip install --upgrade azathoth-ai
azathoth initpython -m pip install --upgrade azathoth-ai
azathoth init1.1 upgrades a 1.0 database in place the first time it opens it, adding the
tables that record a run as it executes. init, which is new in 1.1, then
installs the standard tools, which ship in the package from 1.1 on. A
database holding the composition tools 1.0 shipped as examples gets:
Database: /path/to/azathoth.db (existing)
Installed tool run_workflow@1.0.0 revision 2.
Installed tool loop_workflow@1.1.0 revision 1.
Installed tool map_workflow@1.0.0 revision 1.
Installed tool json_select@1.0.0 revision 1.
Installed tool json_object@1.0.0 revision 1.
Installed tool json_merge@1.0.0 revision 1.
Installed tool validate_json@1.0.0 revision 1.
Installed tool chunk_text@1.0.0 revision 1.
Installed tool join_text@1.0.0 revision 1.
Installed tool render_template@1.0.0 revision 1.
Installed tool split_s3_object@1.0.0 revision 1.
Installed tool read_s3_object@1.0.0 revision 1.
Two changes can stop a workflow that ran on 1.0:
- Process tools no longer inherit Azathoth's environment. The standard tools
grant themselves what they need; a process tool of your own that relied
on an inherited variable, such as a provider key, must grant it (see
Process Environment). - A workflow that requires
loop_workflow1.0.0, the example 1.0 shipped,
must name 1.1.0. The 1.0.0 implementation grants itself nothing, so its
children no longer seeAZATHOTH_DATABASE, and openazathoth.dbin
whatever directory they run in instead of yours.run_workflow1.0.0
needs no change:initgives it its grants as its next revision.
Azathoth 1.0.0
Azathoth 1.0.0 is the first stable release of the open-source engine for building LLM workflows by composition rather than code, and improving them with measured evidence.
Install it with pip install azathoth-ai. The install guide covers macOS and Windows.
Highlights
- Workflows are JSON documents that compose prompt, tool and child-workflow steps, with dependencies, conditions, retries and failure policies. Code is for tools.
- Prompt steps state model requirements rather than naming models. Azathoth chooses from the models you authorize, through OpenRouter.
- Benchmarks support exact, normalized, schema and model-judged semantic cases. Runs marked bad become new cases.
- The optimizer searches for strictly cheaper models and ranks candidates on quality, reliability, latency and cost. Its report shows the model each winning step used.
- Promotion is explicit: production runs exact models, with revision history and an invocation log.
- Child workflows and loops are built from tools, and nest up to eight levels deep.
- Eight examples, from a word count to a novel, each with benchmarks and end-to-end tests.
- Python 3.11 to 3.13 on Linux, macOS and Windows.
Documentation
Getting Started · Examples Tour · Concepts · CLI Reference
Support the project on Patreon.