Skip to content

Releases

Azathoth 1.4.0

Choose a tag to compare

@OMontano OMontano released this 12 Nov 21:35
5540263
v1.4.0

Azathoth 1.4.0

Azathoth 1.4.0b1

Azathoth 1.4.0b1 Pre-release
Pre-release

Choose a tag to compare

@OMontano OMontano released this 12 Nov 18:32
86b5ee7
  • 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 equivalent azathoth command, 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, as azathoth job run does, 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.api runs and invokes a workflow on a file: RunFile holds 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.api checks 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.api reads 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.api tries 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; run azathoth init once 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, as Name <email> or Name, or else the
    operating system's username; a malformed AZATHOTH_AUTHOR stops the
    import, authorizing a model, and adding a benchmark case. The standard
    tools are recorded as Azathoth's
    (ADR 0122).
  • workflow show and benchmark show name each revision's digest, parent
    and author, and history lines end with who imported each revision when
    that is known
    (ADR 0122).
  • azathoth.api reports 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, ToolImport and BenchmarkImport, which say whether a
    revision was created; api.open takes the author to record
    (ADR 0122).
  • Sensitivity labels: a run's input, a job's input and a benchmark case may
    be labelled public, internal or restricted, with --sensitivity,
    an input source's sensitivity or the service API's sensitivity=.
    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, or model policy at any
    time, which also shows who declared it and when. The database schema is
    now version 4; run azathoth init once 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, and get_invocation returns 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, a Sensitivity: line in show commands for data that is
    not internal, a warning on standard error from every command that prints
    restricted data, and the azathoth.sensitivity span attribute. Tools are
    not gated by labels in 1.4
    (ADR 0123).
  • A remote: azathoth remote serve serves an instance's workflows, tools
    and benchmarks over HTTP, for other instances to push to and pull from,
    with the new remote extra. azathoth remote push and pull, and the
    service API's instance.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; list and revoke manage them, and
    a client reads its token from AZATHOTH_REMOTE_TOKEN. The database schema
    is now version 5; run azathoth init once 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 the azathoth.remote entry-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's models.matching(..., scope="catalog") matches every
    model the providers serve, marked authorized or not, for a pulled
    workflow's steps. The container image includes the remote extra
    (ADR 0124).
  • azathoth.api's remote.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/portfolio and /v1/credentials,
    read-only, under a new read_portfolio action and portfolio_read audit
    event. The credential check is asked by name, and never returns a value
    (ADR 0125).
  • azathoth remote push wa...
Read more

Azathoth 1.4.0a3

Azathoth 1.4.0a3 Pre-release
Pre-release

Choose a tag to compare

@OMontano OMontano released this 10 Nov 17:02
1412910
  • 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 equivalent azathoth command, 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, as azathoth job run does, 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.api runs and invokes a workflow on a file: RunFile holds 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.api checks 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.api reads 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.api tries 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; run azathoth init once 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, as Name <email> or Name, or else the
    operating system's username; a malformed AZATHOTH_AUTHOR stops the
    import, authorizing a model, and adding a benchmark case. The standard
    tools are recorded as Azathoth's
    (ADR 0122).
  • workflow show and benchmark show name each revision's digest, parent
    and author, and history lines end with who imported each revision when
    that is known
    (ADR 0122).
  • azathoth.api reports 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, ToolImport and BenchmarkImport, which say whether a
    revision was created; api.open takes the author to record
    (ADR 0122).

Azathoth 1.4.0a2

Azathoth 1.4.0a2 Pre-release
Pre-release

Choose a tag to compare

@OMontano OMontano released this 10 Nov 05:29
0d5779d
  • 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 equivalent azathoth command, 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, as azathoth job run does, 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.api runs and invokes a workflow on a file: RunFile holds 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.api checks 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.api reads 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.api tries 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 1.4.0a1 Pre-release
Pre-release

Choose a tag to compare

@OMontano OMontano released this 08 Nov 21:20
1d0f40f
  • 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 equivalent azathoth command, 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, as azathoth job run does, 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

Choose a tag to compare

@OMontano OMontano released this 05 Nov 19:53
56ad1c7

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-mcp serves 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 as job run runs a job request: a repeated
    key replays, an interrupted invocation resumes, and the caller is recorded
    with it. get_invocation returns 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 init
python -m pip install --upgrade azathoth-ai
azathoth init

To 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

Choose a tag to compare

@OMontano OMontano released this 03 Nov 22:04
4bd8ca3

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_text and render_template.
  • A step input may be a constant, written in the workflow document
    (ADR 0094).
  • Loops are budgeted from their settings: loop_workflow 1.1.0 takes a
    budget_seconds, and every process tool is told its own timeout
    (ADR 0093).
  • map_workflow runs 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:// or s3:// 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_object streams
    an object into chunk objects, and read_s3_object reads one back
    (ADR 0110).

Running in Production

  • PostgreSQL keeps durable state for many processes at once, selected by
    a postgresql:// 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),
    and workflow promote --experiment deploys 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 init
python -m pip install --upgrade azathoth-ai
azathoth init

1.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_workflow 1.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 see AZATHOTH_DATABASE, and open azathoth.db in
    whatever directory they run in instead of yours. run_workflow 1.0.0
    needs no change: init gives it its grants as its next revision.

Azathoth 1.0.0

Choose a tag to compare

@OMontano OMontano released this 27 Oct 14:24
d3f97ab

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.