aethergraph 0.1.0a1__tar.gz → 0.1.0a2__tar.gz

aethergraph-0.1.0a2/MANIFEST.in

@@ -0,0 +1,5 @@
+prune tests
+prune examples
+prune src/aethergraph/demos
+
+global-exclude *.py[cod] __pycache__ .DS_Store

{aethergraph-0.1.0a1/src/aethergraph.egg-info → aethergraph-0.1.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aethergraph
-Version: 0.1.0a1
+Version: 0.1.0a2
 Summary: Python-first agentic DAG execution framework
 Author-email: Zhaocheng Liu <zhaocheng@aiperture.io>
 License:                                 Apache License
@@ -199,7 +199,7 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: fastapi>=0.110
+Requires-Dist: fastapi<1.0,>=0.110
 Requires-Dist: uvicorn[standard]>=0.31
 Requires-Dist: pydantic>=2.6
 Requires-Dist: pydantic-settings>=2.2
@@ -239,6 +239,7 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.0.0; extra == "test"
 Requires-Dist: pytest-asyncio>=0.23; extra == "test"
 Requires-Dist: coverage>=7.4; extra == "test"
+Requires-Dist: trio; extra == "test"
 Dynamic: license-file
 
 <p align="center">
@@ -247,9 +248,13 @@ Dynamic: license-file
 
 # 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.
+**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.
+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.
+
+* **[Introduction](https://aiperture.io)**
+* **[Docs](https://aiperture.github.io/aethergraph-docs/)**
+* **[Examples](https://github.com/AIperture/aethergraph-examples)**
 
 ---
 
@@ -257,8 +262,9 @@ Use AetherGraph to prototype interactive assistants, simulation/optimization loo
 
 * Python **3.10+**
 * macOS, Linux, or Windows
-* *(Optional)* LLM API keys (OpenAI, Anthropic, Google, etc.)
-* *(Optional extras)* `slack` adapter
+* *(Suggested)* LLM API keys (OpenAI, Anthropic, Google, etc.)
+* *(Optional)* `slack` or `telegram` token. See [Channel Setup](https://aiperture.github.io/aethergraph-docs/channel-setup/introduction/)
+* *(Optional UI)* A modern browser to use the built-in AetherGraph web UI
 
 ---
 
@@ -280,6 +286,8 @@ pip install "aethergraph[slack]"
 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)
 
@@ -294,11 +302,16 @@ pip install -e .
 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 (optional)
+## Configure
 
-Most examples run without an LLM, but for LLM‑backed flows set keys via environment variables or a local secrets file.
+Aethergraph can run without an LLM, but for many LLM-backed flows in [examples](https://github.com/AIperture/aethergraph-examples), set keys via environment variables or a local secrets file.
 
 Minimal example (OpenAI):
 
@@ -310,7 +323,7 @@ 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):
+Or inline in a script at runtime (for on-demand key setting):
 
 ```python
 from aethergraph.runtime import register_llm_client
@@ -323,45 +336,131 @@ open_ai_client = register_llm_client(
 )
 ```
 
-See our docs for setup of **external channel** methods for real-time interaction. 
-
+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.
+> **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.
 
 ---
 
-## Quickstart (60 seconds)
-
-1. Verify install:
+## Verify install
 
 ```bash
 python -c "import aethergraph; print('AetherGraph OK, version:', getattr(aethergraph, '__version__', 'dev'))"
 ```
 
-2. Run a minimal graph:
+---
+
+## 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:
+
+```text
+my_project/
+  demos/
+    __init__.py
+    chat_demo.py
+  aethergraph_data/   # workspace (created automatically as needed)
+```
+
+Example `chat_demo.py`:
+
+```python
+# 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**.
+
+### 2. Start the server with UI from the terminal (recommended)
+
+From `my_project/`:
 
 ```bash
-python - <<'PY'
-from aethergraph import graph_fn, NodeContext
-from aethergraph.runner import run 
+aethergraph serve \
+  --project-root . \
+  --load-module demos \
+  --reload
+```
 
-@graph_fn(name="hello_world")
-async def hello_world(context: NodeContext):
-    print("Hello from AetherGraph!")
-    return {"ok": True}
+This will:
 
-run(hello_world)
-PY
+* 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:
+
+```text
+[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_data
+[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:
+
+```python
+# start_server.py
+from aethergraph import start_server
+
+if __name__ == "__main__":
+    start_server(
+        workspace="./aethergraph_data",
+        project_root=".",
+        load_module=["demos"],
+        host="127.0.0.1",
+        port=8745,
+    )
+```
+
+```bash
+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. A growing gallery of standalone examples will be published at:
-
-* **Repo:** [https://github.com/AIperture/aethergraph-examples](https://github.com/AIperture/aethergraph-examples)
-* **Path:** `examples/`
+Quick-start scripts live under `examples/` in this repo.
 
 Run an example:
 
@@ -370,14 +469,22 @@ cd examples
 python hello_world.py
 ```
 
+A growing gallery of standalone examples and recipes lives under:
+
+* **Repo:** [https://github.com/AIperture/aethergraph-examples](https://github.com/AIperture/aethergraph-examples)
+
 ---
 
 ## 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.
+* **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={...}`.
 
 ---
 
@@ -407,4 +514,4 @@ pytest -q
 
 ## License
 
-**Apache‑2.0** — see `LICENSE`.
+**Apache-2.0** — see `LICENSE`.

aethergraph-0.1.0a2/README.md

@@ -0,0 +1,273 @@
+<p align="center">
+  <img src="assets/logo.png" alt="AetherGraph" width="360"/>
+</p>
+
+# 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.
+
+* **[Introduction](https://aiperture.io)**
+* **[Docs](https://aiperture.github.io/aethergraph-docs/)**
+* **[Examples](https://github.com/AIperture/aethergraph-examples)**
+
+---
+
+## Requirements
+
+* Python **3.10+**
+* macOS, Linux, or Windows
+* *(Suggested)* LLM API keys (OpenAI, Anthropic, Google, etc.)
+* *(Optional)* `slack` or `telegram` token. See [Channel Setup](https://aiperture.github.io/aethergraph-docs/channel-setup/introduction/)
+* *(Optional UI)* A modern browser to use the built-in AetherGraph web UI
+
+---
+
+## Install
+
+### Option A — PyPI (recommended)
+
+```bash
+pip install aethergraph
+```
+
+Optional extras:
+
+```bash
+# 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)
+
+```bash
+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](https://github.com/AIperture/aethergraph-examples), set keys via environment variables or a local secrets file.
+
+Minimal example (OpenAI):
+
+```ini
+# .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):
+
+```python
+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.
+
+---
+
+## Verify install
+
+```bash
+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:
+
+```text
+my_project/
+  demos/
+    __init__.py
+    chat_demo.py
+  aethergraph_data/   # workspace (created automatically as needed)
+```
+
+Example `chat_demo.py`:
+
+```python
+# 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**.
+
+### 2. Start the server with UI from the terminal (recommended)
+
+From `my_project/`:
+
+```bash
+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:
+
+```text
+[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_data
+[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:
+
+```python
+# start_server.py
+from aethergraph import start_server
+
+if __name__ == "__main__":
+    start_server(
+        workspace="./aethergraph_data",
+        project_root=".",
+        load_module=["demos"],
+        host="127.0.0.1",
+        port=8745,
+    )
+```
+
+```bash
+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:
+
+```bash
+cd examples
+python hello_world.py
+```
+
+A growing gallery of standalone examples and recipes lives under:
+
+* **Repo:** [https://github.com/AIperture/aethergraph-examples](https://github.com/AIperture/aethergraph-examples)
+
+---
+
+## 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:
+
+```bash
+pip install -e .[dev]
+pytest -q
+```
+
+---
+
+## Project Links
+
+* **Source:** [https://github.com/AIperture/aethergraph](https://github.com/AIperture/aethergraph)
+* **Issues:** [https://github.com/AIperture/aethergraph/issues](https://github.com/AIperture/aethergraph/issues)
+* **Examples:** [https://github.com/AIperture/aethergraph-examples](https://github.com/AIperture/aethergraph-examples)
+* **Docs (preview):** [https://aiperture.github.io/aethergraph-docs/](https://aiperture.github.io/aethergraph-docs/)
+
+---
+
+## License
+
+**Apache-2.0** — see `LICENSE`.

{aethergraph-0.1.0a1 → aethergraph-0.1.0a2}/pyproject.toml

@@ -4,16 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aethergraph"
-version = "0.1.0a1"
+version = "0.1.0a2"
 description = "Python-first agentic DAG execution framework"
 readme = "README.md"
 license = { file = "LICENSE" }
 authors = [{ name = "Zhaocheng Liu", email = "zhaocheng@aiperture.io" }]
 requires-python = ">=3.10"
 
-# Conservative lower bounds; you can tighten as you stabilize.
+# Conservative lower bounds; tighten as stabilize.
 dependencies = [
-  "fastapi>=0.110",
+  "fastapi>=0.110,<1.0",
   "uvicorn[standard]>=0.31",
   "pydantic>=2.6",
   "pydantic-settings>=2.2",
@@ -50,7 +50,9 @@ Documentation = "https://aiperture.github.io/aethergraph-docs/"
 Issues = "https://github.com/AIperture/aethergraph/issues"
 
 [project.scripts]
-aethergraph = "aethergraph.cli.main:main"
+aethergraph = "aethergraph.__main__:main"
+aethergraph-server = "aethergraph.server.server:main"
+
 
 [project.optional-dependencies]
 # Keep extras small and purposeful; add more as modularize features.
@@ -81,18 +83,26 @@ docs = [
 test = [
   "pytest>=8.0.0",
   "pytest-asyncio>=0.23",
-  "coverage>=7.4"
+  "coverage>=7.4",
+  "trio"
 ]
 
 [tool.setuptools]
 package-dir = { "" = "src" }
-include-package-data = true
+include-package-data = false  # specify in later
 license-files = ["LICENSE*", "NOTICE*", "COPYING*"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
-# If you want to exclude experimental dirs, uncomment and adjust:
-# exclude = ["tests*", "examples*"]
+exclude = [
+  "tests*", 
+  "examples*",
+  "aethergraph.demos*",
+  "aethergraph.demos.*"
+]
+
+[tool.setuptools.exclude-package-data]
+aethergraph = ["demos/**"]
 
 [tool.setuptools.package-data]
 # Ship non-Python assets bundled with the package (adjust as needed)
@@ -102,6 +112,7 @@ aethergraph = [
   "**/*.yml",
   "**/*.txt",
   "v*/**/templates/**/*",
+  "server/ui_static/**",
 ]
 
 # -------------------------

{aethergraph-0.1.0a1 → aethergraph-0.1.0a2}/src/aethergraph/__init__.py

@@ -1,8 +1,7 @@
-__version__ = "0.1.0a1"
+__version__ = "0.1.0a2"
 
+import logging
 
-# Server
-# Channel buttons
 from .contracts.services.channel import Button
 
 # Graphs
@@ -24,6 +23,8 @@ from .server.start import (
     stop_server,  # stop the sidecar server
 )
 
+logging.getLogger("aethergraph").addHandler(logging.NullHandler())
+
 __all__ = [
     # Server
     "start_server",
@@ -34,16 +35,9 @@ __all__ = [
     "graph_fn",
     "graphify",
     "TaskGraph",
-    "RuntimeEnv",
     "NodeContext",
     # Services
     "Service",
     # Channel buttons
     "Button",
 ]
-
-
-# Setup a default null logger to avoid "No handler found" warnings
-import logging
-
-logging.getLogger("aethergraph").addHandler(logging.NullHandler())