aethergraph 0.1.0a1__py3-none-any.whl

aethergraph/services/waits/wait_registry.py

@@ -0,0 +1,91 @@
+import asyncio
+import threading
+from typing import Any
+
+
+class WaitRegistry:
+    """
+    In-process registry for cooperative waits.
+    - register(token): binds a Future to the *current* running loop
+    - resolve(token, payload): from any thread/loop, completes that Future
+    - cancel(token): cancels a pending wait
+
+    Use this only for cooperative (same-process) resumes.
+    All other resumes should go via ResumeBus/Scheduler.
+    """
+
+    def __init__(self) -> None:
+        # token -> (owning_loop, future)
+        self._futs: dict[str, tuple[asyncio.AbstractEventLoop, asyncio.Future]] = {}
+        self._lock = threading.RLock()
+        # If a resume arrives before register()
+        self._pending_payloads: dict[str, Any] = {}
+
+    def register(self, token: str) -> asyncio.Future:
+        """Create or reuse a Future on the current loop; deliver any early payload."""
+        loop = asyncio.get_running_loop()
+        with self._lock:
+            entry = self._futs.get(token)
+            if entry:
+                el, fut = entry
+                if fut.done() or getattr(el, "is_closed", lambda: False)():
+                    fut = loop.create_future()
+                    self._futs[token] = (loop, fut)
+            else:
+                fut = loop.create_future()
+                self._futs[token] = (loop, fut)
+                # deliver early resume if present
+                if token in self._pending_payloads:
+                    payload = self._pending_payloads.pop(token)
+                    loop.call_soon(fut.set_result, payload)
+            return fut
+
+    def resolve(self, token: str, payload: dict | None = None) -> bool:
+        """Resolve from any thread; returns True if delivered to a registered Future."""
+        payload = payload or {}
+        with self._lock:
+            entry = self._futs.pop(token, None)
+            if not entry:
+                # resume before register: stash
+                self._pending_payloads[token] = payload
+                return False
+            loop, fut = entry
+
+        if not fut.done():
+            loop.call_soon_threadsafe(fut.set_result, payload)
+        return True
+
+    def cancel(self, token: str, exc: BaseException | None = None) -> bool:
+        """Cancel from any thread; returns True if a Future was present."""
+        with self._lock:
+            entry = self._futs.pop(token, None)
+            self._pending_payloads.pop(token, None)
+        if not entry:
+            return False
+        loop, fut = entry
+        if not fut.done():
+            loop.call_soon_threadsafe(
+                fut.set_exception, exc or asyncio.CancelledError(f"Wait cancelled: {token}")
+            )
+        return True
+
+    # --- optional helpers ---
+    def has(self, token: str) -> bool:
+        with self._lock:
+            return token in self._futs or token in self._pending_payloads
+
+    def size(self) -> int:
+        with self._lock:
+            return len(self._futs)
+
+    def shutdown(self) -> None:
+        """Best-effort cleanup; cancels outstanding futures."""
+        with self._lock:
+            items = list(self._futs.items())
+            self._futs.clear()
+            self._pending_payloads.clear()
+        for _, (loop, fut) in items:
+            if not fut.done():
+                loop.call_soon_threadsafe(
+                    fut.set_exception, asyncio.CancelledError("Registry shutdown")
+                )

aethergraph/services/wakeup/memory_queue.py

@@ -0,0 +1,57 @@
+from dataclasses import dataclass
+import heapq
+import threading
+import time
+import uuid
+
+
+@dataclass
+class _Lease:
+    id: str
+    msg: dict
+    visibility_deadline: float
+
+
+class ThreadSafeWakeupQueue:
+    def __init__(self):
+        self._ready: list[tuple[float, int, dict]] = []
+        self._inflight: dict[str, _Lease] = {}  # lease.id -> lease
+        self._ctr = 0
+        self._lock = threading.RLock()
+
+    async def enqueue(self, topic: str, msg: dict, delay_s: float = 0) -> str:
+        with self._lock:
+            self._ctr += 1
+            heapq.heappush(self._ready, (time.time() + delay_s, self._ctr, msg))
+            return msg.get("job_id") or str(self._ctr)
+
+    async def lease(self, topic: str, max_items: int = 1, lease_s: int = 60) -> list[_Lease]:
+        out = []
+        now = time.time()
+        with self._lock:
+            while self._ready and len(out) < max_items:
+                visible_at, _, msg = self._ready[0]
+                if visible_at > now:
+                    break
+                heapq.heappop(self._ready)
+                lid = uuid.uuid4().hex
+                lease = _Lease(lid, msg, now + lease_s)
+                self._inflight[lid] = lease
+                out.append(lease)
+        return out
+
+    async def extend(self, lease: _Lease, lease_s: int) -> None:
+        with self._lock:
+            if lease.id in self._inflight:
+                self._inflight[lease.id].visibility_deadline = time.time() + lease_s
+
+    async def ack(self, lease: _Lease) -> None:
+        with self._lock:
+            self._inflight.pop(lease.id, None)
+
+    async def nack(self, lease: _Lease, requeue_delay_s: float = 5) -> None:
+        with self._lock:
+            lease = self._inflight.pop(lease.id, None)
+            if lease:
+                self._ctr += 1
+                heapq.heappush(self._ready, (time.time() + requeue_delay_s, self._ctr, lease.msg))

aethergraph/services/wakeup/scanner_producer.py

@@ -0,0 +1,56 @@
+import asyncio
+from datetime import datetime, timezone
+
+from aethergraph.contracts.services.wakeup import WakeupQueue
+
+
+# services/wakeup/scanner_producer.py
+class ScannerProducer:
+    def __init__(self, store, queue: WakeupQueue, logger, tick_sec=1.0, topic="default"):
+        self.store = store
+        self.queue = queue
+        self.logger = logger
+        self.tick_sec = tick_sec
+        self.topic = topic
+        self._task = None
+        self._stopped = asyncio.Event()
+
+    def start(self):
+        if not self._task:
+            self._task = asyncio.create_task(self._loop())
+
+    async def stop(self):
+        self._stopped.set()
+        if self._task:
+            await self._task
+
+    async def _loop(self):
+        while not self._stopped.is_set():
+            await asyncio.sleep(self.tick_sec)
+            now = datetime.now(timezone.utc)
+            for c in self._iter_continuations():
+                if c.poll:
+                    # poll; if hit -> enqueue
+                    payload = await self._try_poll(c)
+                    if payload is not None:
+                        await self.queue.enqueue(
+                            self.topic,
+                            {
+                                "kind": "resume",
+                                "run_id": c.run_id,
+                                "node_id": c.node_id,
+                                "token": c.token,
+                                "payload": payload,
+                            },
+                        )
+                elif c.next_wakeup_at and now >= c.next_wakeup_at:
+                    await self.queue.enqueue(
+                        self.topic,
+                        {
+                            "kind": "resume",
+                            "run_id": c.run_id,
+                            "node_id": c.node_id,
+                            "token": c.token,
+                            "payload": {"deadline_fired": True},
+                        },
+                    )

aethergraph/services/wakeup/worker.py

@@ -0,0 +1,31 @@
+import asyncio
+
+from aethergraph.contracts.services.wakeup import WakeupQueue
+
+
+class WakeWorker:
+    def __init__(self, queue: WakeupQueue, resume_bus, logger, topic="default"):
+        self.queue = queue
+        self.resume_bus = resume_bus
+        self.logger = logger
+        self.topic = topic
+
+    async def run_forever(self):
+        while True:
+            leases = await self.queue.lease(self.topic, max_items=1, lease_s=60)
+            if not leases:
+                await asyncio.sleep(0.2)
+                continue
+            lease = leases[0]
+            try:
+                msg = lease.msg
+                await self.resume_bus.enqueue_resume(
+                    run_id=msg["run_id"],
+                    node_id=msg["node_id"],
+                    token=msg["token"],
+                    payload=msg["payload"],
+                )
+                await self.queue.ack(lease)
+            except Exception as e:
+                self.logger.error("resume_failed", err=str(e), node=msg.get("node_id"))
+                await self.queue.nack(lease, requeue_delay_s=2)

aethergraph/tools/__init__.py

@@ -0,0 +1,25 @@
+# redirect tools imports for clean imports
+
+from aethergraph.core.tools.builtins.toolset import (
+    ask_approval,
+    ask_files,
+    ask_text,
+    get_latest_uploads,
+    send_buttons,
+    send_file,
+    send_image,
+    send_text,
+    wait_text,
+)
+
+__all__ = [
+    "ask_approval",
+    "ask_files",
+    "ask_text",
+    "get_latest_uploads",
+    "send_buttons",
+    "send_file",
+    "send_image",
+    "send_text",
+    "wait_text",
+]

aethergraph/utils/optdeps.py

@@ -0,0 +1,8 @@
+# src/aethergraph/utils/optdeps.py
+def require(pkg: str, extra: str):
+    try:
+        __import__(pkg)
+    except ImportError as e:
+        raise RuntimeError(
+            f"{pkg} is required for this feature. Install with: pip install 'aethergraph[{extra}]'"
+        ) from e

aethergraph-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,410 @@
+Metadata-Version: 2.4
+Name: aethergraph
+Version: 0.1.0a1
+Summary: Python-first agentic DAG execution framework
+Author-email: Zhaocheng Liu <zhaocheng@aiperture.io>
+License:                                 Apache License
+                                Version 2.0, January 2004
+                            http://www.apache.org/licenses/
+        
+        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+        1. Definitions.
+        
+            "License" shall mean the terms and conditions for use, reproduction,
+            and distribution as defined by Sections 1 through 9 of this document.
+        
+            "Licensor" shall mean the copyright owner or entity authorized by
+            the copyright owner that is granting the License.
+        
+            "Legal Entity" shall mean the union of the acting entity and all
+            other entities that control, are controlled by, or are under common
+            control with that entity. For the purposes of this definition,
+            "control" means (i) the power, direct or indirect, to cause the
+            direction or management of such entity, whether by contract or
+            otherwise, or (ii) ownership of fifty percent (50%) or more of the
+            outstanding shares, or (iii) beneficial ownership of such entity.
+        
+            "You" (or "Your") shall mean an individual or Legal Entity
+            exercising permissions granted by this License.
+        
+            "Source" form shall mean the preferred form for making modifications,
+            including but not limited to software source code, documentation
+            source, and configuration files.
+        
+            "Object" form shall mean any form resulting from mechanical
+            transformation or translation of a Source form, including but
+            not limited to compiled object code, generated documentation,
+            and conversions to other media types.
+        
+            "Work" shall mean the work of authorship, whether in Source or
+            Object form, made available under the License, as indicated by a
+            copyright notice that is included in or attached to the work
+            (an example is provided in the Appendix below).
+        
+            "Derivative Works" shall mean any work, whether in Source or Object
+            form, that is based on (or derived from) the Work and for which the
+            editorial revisions, annotations, elaborations, or other modifications
+            represent, as a whole, an original work of authorship. For the purposes
+            of this License, Derivative Works shall not include works that remain
+            separable from, or merely link (or bind by name) to the interfaces of,
+            the Work and Derivative Works thereof.
+        
+            "Contribution" shall mean any work of authorship, including
+            the original version of the Work and any modifications or additions
+            to that Work or Derivative Works thereof, that is intentionally
+            submitted to Licensor for inclusion in the Work by the copyright owner
+            or by an individual or Legal Entity authorized to submit on behalf of
+            the copyright owner. For the purposes of this definition, "submitted"
+            means any form of electronic, verbal, or written communication sent
+            to the Licensor or its representatives, including but not limited to
+            communication on electronic mailing lists, source code control systems,
+            and issue tracking systems that are managed by, or on behalf of, the
+            Licensor for the purpose of discussing and improving the Work, but
+            excluding communication that is conspicuously marked or otherwise
+            designated in writing by the copyright owner as "Not a Contribution."
+        
+            "Contributor" shall mean Licensor and any individual or Legal Entity
+            on behalf of whom a Contribution has been received by Licensor and
+            subsequently incorporated within the Work.
+        
+        2. Grant of Copyright License. Subject to the terms and conditions of
+            this License, each Contributor hereby grants to You a perpetual,
+            worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+            copyright license to reproduce, prepare Derivative Works of,
+            publicly display, publicly perform, sublicense, and distribute the
+            Work and such Derivative Works in Source or Object form.
+        
+        3. Grant of Patent License. Subject to the terms and conditions of
+            this License, each Contributor hereby grants to You a perpetual,
+            worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+            (except as stated in this section) patent license to make, have made,
+            use, offer to sell, sell, import, and otherwise transfer the Work,
+            where such license applies only to those patent claims licensable
+            by such Contributor that are necessarily infringed by their
+            Contribution(s) alone or by combination of their Contribution(s)
+            with the Work to which such Contribution(s) was submitted. If You
+            institute patent litigation against any entity (including a
+            cross-claim or counterclaim in a lawsuit) alleging that the Work
+            or a Contribution incorporated within the Work constitutes direct
+            or contributory patent infringement, then any patent licenses
+            granted to You under this License for that Work shall terminate
+            as of the date such litigation is filed.
+        
+        4. Redistribution. You may reproduce and distribute copies of the
+            Work or Derivative Works thereof in any medium, with or without
+            modifications, and in Source or Object form, provided that You
+            meet the following conditions:
+        
+            (a) You must give any other recipients of the Work or
+                Derivative Works a copy of this License; and
+        
+            (b) You must cause any modified files to carry prominent notices
+                stating that You changed the files; and
+        
+            (c) You must retain, in the Source form of any Derivative Works
+                that You distribute, all copyright, patent, trademark, and
+                attribution notices from the Source form of the Work,
+                excluding those notices that do not pertain to any part of
+                the Derivative Works; and
+        
+            (d) If the Work includes a "NOTICE" text file as part of its
+                distribution, then any Derivative Works that You distribute must
+                include a readable copy of the attribution notices contained
+                within such NOTICE file, excluding those notices that do not
+                pertain to any part of the Derivative Works, in at least one
+                of the following places: within a NOTICE text file distributed
+                as part of the Derivative Works; within the Source form or
+                documentation, if provided along with the Derivative Works; or,
+                within a display generated by the Derivative Works, if and
+                wherever such third-party notices normally appear. The contents
+                of the NOTICE file are for informational purposes only and
+                do not modify the License. You may add Your own attribution
+                notices within Derivative Works that You distribute, alongside
+                or as an addendum to the NOTICE text from the Work, provided
+                that such additional attribution notices cannot be construed
+                as modifying the License.
+        
+            You may add Your own copyright statement to Your modifications and
+            may provide additional or different license terms and conditions
+            for use, reproduction, or distribution of Your modifications, or
+            for any such Derivative Works as a whole, provided Your use,
+            reproduction, and distribution of the Work otherwise complies with
+            the conditions stated in this License.
+        
+        5. Submission of Contributions. Unless You explicitly state otherwise,
+            any Contribution intentionally submitted for inclusion in the Work
+            by You to the Licensor shall be under the terms and conditions of
+            this License, without any additional terms or conditions.
+            Notwithstanding the above, nothing herein shall supersede or modify
+            the terms of any separate license agreement you may have executed
+            with Licensor regarding such Contributions.
+        
+        6. Trademarks. This License does not grant permission to use the trade
+            names, trademarks, service marks, or product names of the Licensor,
+            except as required for reasonable and customary use in describing the
+            origin of the Work and reproducing the content of the NOTICE file.
+        
+        7. Disclaimer of Warranty. Unless required by applicable law or
+            agreed to in writing, Licensor provides the Work (and each
+            Contributor provides its Contributions) on an "AS IS" BASIS,
+            WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+            implied, including, without limitation, any warranties or conditions
+            of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+            PARTICULAR PURPOSE. You are solely responsible for determining the
+            appropriateness of using or redistributing the Work and assume any
+            risks associated with Your exercise of permissions under this License.
+        
+        8. Limitation of Liability. In no event and under no legal theory,
+            whether in tort (including negligence), contract, or otherwise,
+            unless required by applicable law (such as deliberate and grossly
+            negligent acts) or agreed to in writing, shall any Contributor be
+            liable to You for damages, including any direct, indirect, special,
+            incidental, or consequential damages of any character arising as a
+            result of this License or out of the use or inability to use the
+            Work (including but not limited to damages for loss of goodwill,
+            work stoppage, computer failure or malfunction, or any and all
+            other commercial damages or losses), even if such Contributor
+            has been advised of the possibility of such damages.
+        
+        9. Accepting Warranty or Additional Liability. While redistributing
+            the Work or Derivative Works thereof, You may choose to offer,
+            and charge a fee for, acceptance of support, warranty, indemnity,
+            or other liability obligations and/or rights consistent with this
+            License. However, in accepting such obligations, You may act only
+            on Your own behalf and on Your sole responsibility, not on behalf
+            of any other Contributor, and only if You agree to indemnify,
+            defend, and hold each Contributor harmless for any liability
+            incurred by, or claims asserted against, such Contributor by reason
+            of your accepting any such warranty or additional liability.
+        
+        END OF TERMS AND CONDITIONS
+Project-URL: Homepage, https://github.com/AIperture/aethergraph
+Project-URL: Repository, https://github.com/AIperture/aethergraph
+Project-URL: Documentation, https://aiperture.github.io/aethergraph-docs/
+Project-URL: Issues, https://github.com/AIperture/aethergraph/issues
+Keywords: agents,workflow,DAG,LLM,orchestration,research,aethergraph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.31
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: networkx>=3.1
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: jsonschema>=4.18
+Requires-Dist: httpx>=0.27
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: slack
+Requires-Dist: slack_sdk>=3.27.0; extra == "slack"
+Requires-Dist: aiohttp>=3.9; extra == "slack"
+Provides-Extra: telegram
+Requires-Dist: aiohttp>=3.9; extra == "telegram"
+Provides-Extra: webhook
+Requires-Dist: aiohttp>=3.9; extra == "webhook"
+Provides-Extra: discord
+Requires-Dist: aiohttp>=3.9; extra == "discord"
+Provides-Extra: channels
+Requires-Dist: aethergraph[slack]; extra == "channels"
+Requires-Dist: aethergraph[telegram]; extra == "channels"
+Requires-Dist: aethergraph[webhook]; extra == "channels"
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu>=1.7.4; extra == "faiss"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: black>=24.1.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: types-requests>=2.31.0.10; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+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"
+Dynamic: license-file
+
+<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.
+
+---
+
+## Requirements
+
+* Python **3.10+**
+* macOS, Linux, or Windows
+* *(Optional)* LLM API keys (OpenAI, Anthropic, Google, etc.)
+* *(Optional extras)* `slack` adapter
+
+---
+
+## 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]"
+```
+
+
+### 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]"
+```
+
+---
+
+## Configure (optional)
+
+Most examples run without an LLM, but for LLM‑backed flows 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 our docs for setup of **external channel** methods 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.
+
+---
+
+## Quickstart (60 seconds)
+
+1. Verify install:
+
+```bash
+python -c "import aethergraph; print('AetherGraph OK, version:', getattr(aethergraph, '__version__', 'dev'))"
+```
+
+2. Run a minimal graph:
+
+```bash
+python - <<'PY'
+from aethergraph import graph_fn, NodeContext
+from aethergraph.runner import run 
+
+@graph_fn(name="hello_world")
+async def hello_world(context: NodeContext):
+    print("Hello from AetherGraph!")
+    return {"ok": True}
+
+run(hello_world)
+PY
+```
+
+---
+
+## 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/`
+
+Run an example:
+
+```bash
+cd examples
+python hello_world.py
+```
+
+---
+
+## 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.
+
+---
+
+## 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`.