Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

AetherGraph

AetherGraph

AetherGraph is a Python-first agentic DAG execution framework for building and orchestrating AI-powered workflows. It pairs a clean, function-oriented developer experience with a resilient runtime—event-driven waits, resumable runs, and pluggable services (LLM, memory, artifacts, RAG)—so you can start simple and scale to complex R&D pipelines.

Use AetherGraph to prototype interactive assistants, simulation/optimization loops, data transforms, or multi-step automations without boilerplate. It works with or without LLMs—bring your own tools and services, and compose them into repeatable, observable graphs.


Requirements

  • Python 3.10+
  • macOS, Linux, or Windows
  • (Suggested) LLM API keys (OpenAI, Anthropic, Google, etc.)
  • (Optional) slack or telegram token. See Channel Setup
  • (Optional UI) A modern browser to use the built-in AetherGraph web UI

Install

pip install aethergraph

Optional extras:

# Slack adapter
pip install "aethergraph[slack]"

# Dev tooling (linting, tests, types)
pip install "aethergraph[dev]"

The PyPI package ships with a prebuilt UI bundle, so /ui works out of the box when you run the server locally.

Option B — From source (editable dev mode)

git clone https://github.com/AIperture/aethergraph.git
cd aethergraph

# Base
pip install -e .

# With extras
echo "(optional)" && pip install -e ".[slack,dev]"

When running from source, the backend still works without the frontend bundle. If you want the built-in UI from source, you’ll need to build the frontend and copy the static bundle into aethergraph/server/ui_static/ (see the “UI Guide” in the docs).


Configure

Aethergraph can run without an LLM, but for many LLM-backed flows in examples, set keys via environment variables or a local secrets file.

Minimal example (OpenAI):

# .env (example)
AETHERGRAPH_LLM__ENABLED=true
AETHERGRAPH_LLM__DEFAULT__PROVIDER=openai
AETHERGRAPH_LLM__DEFAULT__MODEL=gpt-4o-mini
AETHERGRAPH_LLM__DEFAULT__API_KEY=sk-...your-key...

Or inline in a script at runtime (for on-demand key setting):

from aethergraph.runtime import register_llm_client

open_ai_client = register_llm_client(
    profile="my_llm",
    provider="openai",
    model="gpt-4o-mini",
    api_key="sk-...your-key...",
)

See the docs for setup of external channel methods (Slack, Telegram, etc.) for real-time interaction.

Where should .env live? In your project root (the directory where you run your Python entry point). You can override with AETHERGRAPH_ENV_FILE=/path/to/.env if needed.

Reasoning defaults can be set per profile in .env and overridden per call:

AETHERGRAPH_LLM__PROFILES__MY_PROFILE__REASONING_EFFORT=high
AETHERGRAPH_LLM__PROFILES__MY_PROFILE__THINKING_MODE=auto

Normalized profile knobs:

  • REASONING_EFFORT: low | medium | high | xhigh | max
  • THINKING_MODE: auto | on | off

Provider mapping:

  • OpenAI: REASONING_EFFORT -> reasoning.effort; THINKING_MODE has no direct wire knob and is treated as advisory only.
  • Anthropic: REASONING_EFFORT -> adaptive thinking effort on newer models; THINKING_MODE=on prefers thinking enabled/adaptive, off omits thinking.
  • Gemini: REASONING_EFFORT -> thinkingLevel on Gemini 3 or thinkingBudget on Gemini 2.5; THINKING_MODE=off maps to minimal/zero-thinking where supported.
  • DeepSeek: REASONING_EFFORT -> reasoning_effort (low/medium map to high, xhigh maps to max); THINKING_MODE -> thinking.type.

compat policy ignores unsupported knobs when safe; strict fails fast. output_format="json" remains a deprecated alias for json_object, and chat_stream() is text-only by contract.


Verify install

python -c "import aethergraph; print('AetherGraph OK, version:', getattr(aethergraph, '__version__', 'dev'))"

Run the built-in UI

AetherGraph ships with a small web UI that lets you:

  • Browse and launch apps (click-to-run graphs)
  • Chat with agents (graph-backed chat endpoints)
  • Inspect runs, sessions, and artifacts

1. Define a simple project module

From your project root:

my_project/
  demos/
    __init__.py
    chat_demo.py
  aethergraph_workspace/   # workspace (created automatically as needed)

Example chat_demo.py:

# demos/chat_demo.py
from aethergraph import graphify

@graphify(
    name="chat_with_memory_demo",
    inputs=[],
    outputs=["turns", "summary"],
    as_app={
        "id": "chat_with_memory_demo",
        "name": "Chat with Memory",
    },
)
def chat_with_memory_demo():
    # Your graph implementation here – tools, nodes, etc.
    ...

as_app={...} tells AetherGraph to expose this graph in the App Gallery of the UI. You can also define graph_fn-based agents with as_agent={...} to appear in the Agent Gallery.

From my_project/:

aethergraph serve \
  --project-root . \
  --load-module demos \
  --reload

This will:

  • Add . to sys.path so demos can be imported.
  • Load any graphs/apps/agents defined in the demos module.
  • Start the API + UI server on http://127.0.0.1:8745.
  • Enable auto-reload: editing your graph files triggers a restart and reload.

You should see log lines like:

[AetherGraph] 🚀  Server started at:  http://127.0.0.1:8745
[AetherGraph] 🖥️  UI:                 http://127.0.0.1:8745/ui
[AetherGraph] 📡  API:                http://127.0.0.1:8745/api/v1/
[AetherGraph] 📂  Workspace:          ./aethergraph_workspace
[AetherGraph] ♻️  Auto-reload:        enabled

Then open in your browser:

  • UI: http://127.0.0.1:8745/ui – App Gallery, Agent Gallery, runs, sessions, artifacts.
  • API: http://127.0.0.1:8745/api/v1/ – for direct HTTP calls.

3. (Optional) Start the server from a Python script

If you prefer to embed the server in your own launcher:

# start_server.py
from aethergraph import start_server

if __name__ == "__main__":
    start_server(
        workspace="./aethergraph_workspace",
        project_root=".",
        load_module=["demos"],
        host="127.0.0.1",
        port=8745,
    )
python start_server.py

For active development, the CLI with --reload is recommended. start_server(...) is better when you want a simple “ship a server in my app” story.

For more details, see the UI Guide section in the docs (server setup, agents/apps, and common pitfalls).


Examples

Quick-start scripts live under examples/ in this repo.

Run an example:

cd examples
python hello_world.py

A growing gallery of standalone examples and recipes lives under:


Troubleshooting

  • ModuleNotFoundError: ensure you installed into the active venv and that your shell is using it.

  • LLM/API errors: confirm provider/model/key configuration (env vars or your local secrets file).

  • Windows path quirks: clear any local cache folders (e.g., .rag/) and re-run; verify write permissions.

  • Slack extra: install with pip install "aethergraph[slack]" if you need Slack channel integration.

  • UI shows no apps/agents:

    • Make sure your module (e.g. demos) is importable under --project-root.
    • Ensure at least one graph has as_app={...} or graph_fn has as_agent={...}.

Contributing (early phase)

  • Use feature branches and open a PR against main.
  • Keep public examples free of real secrets.
  • Run tests locally before pushing.

Dev install:

pip install -e .[dev]
pytest -q


License

Apache-2.0 — see LICENSE.

Metadata

Release files for aethergraph 0.1.0a15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aethergraph 0.1.0a15
File Size Uploaded Provenance Actions
aethergraph-0.1.0a15.tar.gz 3.2 MB Without provenance Details for aethergraph-0.1.0a15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aethergraph 0.1.0a15
File Interpreter ABI Platform Actions
aethergraph-0.1.0a15-py3-none-any.whl Python 3 none any Details for aethergraph-0.1.0a15-py3-none-any.whl

Total release size: 6.6 MB

Release files / aethergraph-0.1.0a15.tar.gz

Download URL aethergraph-0.1.0a15.tar.gz
Size 3.2 MB
Tags Source
SHA-256 checksum
How to use checksums
b4dfe00c666cdc32075d13432d9758520ee75b39fa2c8c3e0575831b61185947
BLAKE2b-256 checksum
How to use checksums
fa9ced087c3ee804c4e0db00e8a2dbc080c056630be6050da5fdfff0ab9ede29
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.12

Release files / aethergraph-0.1.0a15-py3-none-any.whl

Download URL aethergraph-0.1.0a15-py3-none-any.whl
Size 3.4 MB
Tags Python 3
SHA-256 checksum
How to use checksums
c5463f309fac07a90eb64ad755ccfdafb6bda388a848749119aedd7ef040678b
BLAKE2b-256 checksum
How to use checksums
9b47445764fd2a306e36c472fcf56e40fdae8c0cfac9e11b5d2dbf8bf7e588bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.12

Security for aethergraph 0.1.0a15

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page