Metadata-Version: 2.4
Name: aether-observability
Version: 0.4.0
Summary: AETHER — installable observability framework (Python SDK, FastAPI, packaged React console, monitoring engine)
Author: AETHER contributors
License-Expression: MIT
Keywords: observability,anomaly-detection,logs,monitoring,ml,fastapi,dashboard
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn<1.10,>=1.9.1
Requires-Dist: scipy>=1.10
Requires-Dist: joblib>=1.3
Provides-Extra: ml
Requires-Dist: pyarrow>=14.0; extra == "ml"
Requires-Dist: matplotlib>=3.7; extra == "ml"
Requires-Dist: tqdm>=4.65; extra == "ml"
Requires-Dist: requests>=2.31; extra == "ml"
Provides-Extra: api
Requires-Dist: fastapi>=0.110; extra == "api"
Requires-Dist: uvicorn[standard]>=0.27; extra == "api"
Requires-Dist: pydantic>=2.0; extra == "api"
Requires-Dist: httpx>=0.27; extra == "api"
Requires-Dist: psutil>=5.9; extra == "api"
Provides-Extra: dashboard
Requires-Dist: aether-observability[api]; extra == "dashboard"
Requires-Dist: streamlit>=1.32; extra == "dashboard"
Requires-Dist: requests>=2.31; extra == "dashboard"
Requires-Dist: pandas>=2.0; extra == "dashboard"
Provides-Extra: console
Requires-Dist: aether-observability[api,dashboard,ml]; extra == "console"
Provides-Extra: otel
Requires-Dist: opentelemetry-api<2,>=1.27; extra == "otel"
Requires-Dist: opentelemetry-sdk<2,>=1.27; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.27; extra == "otel"
Requires-Dist: opentelemetry-proto<2,>=1.27; extra == "otel"
Provides-Extra: persistence
Requires-Dist: sqlalchemy<3,>=2.0; extra == "persistence"
Requires-Dist: alembic>=1.13; extra == "persistence"
Requires-Dist: psycopg[binary]>=3.1; extra == "persistence"
Provides-Extra: redis
Requires-Dist: redis<6,>=5.0; extra == "redis"
Provides-Extra: oidc
Requires-Dist: PyJWT<3,>=2.8; extra == "oidc"
Requires-Dist: cryptography<51,>=50; extra == "oidc"
Provides-Extra: server
Requires-Dist: aether-observability[api,oidc,otel,persistence,redis]; extra == "server"
Provides-Extra: all
Requires-Dist: aether-observability[api,dashboard,ml,oidc,otel,persistence,redis]; extra == "all"
Provides-Extra: dev
Requires-Dist: aether-observability[all]; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

# AETHER — Installable Observability Framework

**Distribution:** [`aether-observability`](https://pypi.org/project/aether-observability/) · **Import:** `aether` · **Version:** 0.4.0 · **License:** MIT

AETHER is a **complete local observability stack** you can install from pip: a typed Python SDK, a FastAPI monitoring service, a **packaged React console** (static assets inside the wheel — no `npm` at runtime), and an ML-backed log anomaly monitoring engine.

**Who it is for:** developers embedding log monitoring; teams prototyping observability pipelines; students working with LogHub-style HDFS/BGL benchmarks.

**What it is not:** a turnkey production SIEM, a guaranteed incident diagnosis engine, or a package that ships model weights. Artifacts stay **external** (checkout, training, or your own absolute paths). Services do **not** auto-start on `pip install`.

### At a glance

- In-process SDK: `Aether` + `AetherConfig`
- Complete profile: `pip install "aether-observability[all]"` → `aether init` → `aether doctor` → `aether start`
- Packaged React console served at `http://127.0.0.1:<port>/` (HashRouter; same origin as the API)
- Datasets: **HDFS**, **BGL**, **APP** (APP is a synthetic demo model)
- Optional: OTel ingest, Postgres persistence, Redis rate limits, OIDC
- Requires **Python ≥ 3.10** and **scikit-learn ≥1.9.1,<1.10**

---

## Quick start (complete product)

```bash
pip install "aether-observability[all]"
aether init
```

Point `AETHER_ROOT` at the workspace `aether init` created (default under `~/.aether`), place a compatible `.joblib` under `results/…/models/`, then:

```bash
# PowerShell
$env:AETHER_ROOT = "$HOME\.aether"
aether doctor
aether start
```

```bash
# bash
export AETHER_ROOT="$HOME/.aether"
aether doctor
aether start
```

Open the URL printed by `aether start` (default **http://127.0.0.1:8000/**). Stop with `aether stop`. Status: `aether status`.

**Models are not in the wheel.** Train the APP demo from a source checkout (`python scripts/train_app_demo_model.py`) or copy Phase-1 artifacts, then set absolute paths or `AETHER_ROOT`.

### SDK-only

```bash
pip install aether-observability
```

```python
from pathlib import Path
from aether import Aether, AetherConfig

MODEL = Path(r"/absolute/path/to/APP_demo_logistic_regression.joblib")
config = AetherConfig(model_path=MODEL, dataset="APP", window_size=20, stride=20)
with Aether(config=config) as monitor:
    for i in range(20):
        monitor.process({"message": f"event {i}", "level": "INFO", "service": "api"})
    print(monitor.stats().to_dict())
```

---

## 1. Product intro

Cloud and application logs are high-volume and hard to scan by hand. AETHER packages:

1. **SDK** — ingest → normalize → window → joblib inference → predictions / alerts / stats  
2. **Monitoring API** — FastAPI service over the same engine (replay, live tail, RCA, optional OTel)  
3. **React console** — production Vite build shipped inside the wheel and served by the API  
4. **CLI** — `doctor` / `init` / `start` / `stop` / `status` for a localhost-first lifecycle  

Core inference works with the default install (`numpy`, `pandas`, `scikit-learn`, `scipy`, `joblib`). HTTP, console serving, OpenTelemetry, and database extras are optional.

---

## 2. Workflow sequence

```mermaid
flowchart LR
  A[Log records] --> B[Normalize]
  B --> C[Window / unit buffer]
  C --> D[Joblib ML model]
  D --> E[Predictions]
  E --> F[Stats and alerts]
  F --> G[FastAPI + React console]
```

Optional stacks (OTel, RCA, experiments, AI insights) sit on top of this path.

---

## 3. Feature overview

| Category | Status | What exists |
|---|---|---|
| **Core SDK** (`import aether`) | Operational | `Aether`, `AetherConfig`, start/process/stats/alerts/stop |
| **FastAPI monitoring API** | Operational | `aether start` / `aether api` (requires `[api]` or `[all]`) |
| **Packaged React console** | Operational | Built assets in wheel; served at `/` (HashRouter) |
| **CLI lifecycle** | Operational | `version`, `doctor`, `init`, `start`, `stop`, `status` |
| **Joblib inference** | Operational | External artifacts; domain-shift warnings |
| **In-process alerts** | Operational | Cooldown, history, optional SQLite |
| **`[all]`** | Install profile | API + ML + dashboard + otel + persistence + redis + oidc |
| **Legacy Streamlit** | Optional | `aether dashboard` via `[dashboard]` |
| **RCA** (`aether.rca`) | Experimental | Evidence-ranked candidates — not proven causal diagnosis |
| **Resilience experiments** | Demo only | Local `demo-*` services — not a chaos platform |
| **APP demo model** | Demo | Synthetic controlled windows — not production incident diagnosis |

---

## 4. Installation profiles

| Profile | Command | Includes |
|---|---|---|
| **Minimal** | `pip install aether-observability` | Core SDK + inference |
| **Complete** | `pip install "aether-observability[all]"` | API, packaged console deps, ML, OTel, persistence, Redis, OIDC, legacy Streamlit |
| API only | `pip install "aether-observability[api]"` | FastAPI + uvicorn |
| Server | `pip install "aether-observability[server]"` | api + otel + persistence + redis + oidc |
| Dev | `pip install "aether-observability[dev]"` | `[all]` + pytest, ruff, mypy, build, twine |

React static assets are **inside the wheel**. Node.js is required only to *rebuild* the console from `web/` (contributors: `python scripts/build_console.py`).

---

## 5. CLI

```text
aether --help
aether version
aether doctor          # install / config / model / assets checks
aether init [--root PATH] [--force]
aether start [--host 127.0.0.1] [--port 8000] [--foreground]
aether status [--json]
aether stop
aether console         # how the packaged UI is served
aether api             # foreground API only (legacy-compatible)
aether dashboard       # legacy Streamlit
```

Defaults bind **127.0.0.1**. Non-loopback binds require auth (`AETHER_AUTH_ENABLED` + `AETHER_API_KEYS`). See [docs/SECURITY.md](docs/SECURITY.md).

---

## 6. Model and config setup

| Source | Notes |
|---|---|
| `aether init` | Creates `configs/monitoring_config.json` + dirs under `AETHER_HOME` / `--root` (no overwrite unless `--force`) |
| Repository / local training | Phase-1 and APP scripts write under `results/…` |
| Wheel / PyPI install | **Does not** embed `.joblib` files |
| `AETHER_ROOT` | Points at a workspace containing `configs/` and `results/` |
| `AETHER_CONFIG` | Absolute path to a monitoring config JSON |

| Dataset | Example artifact (local, not in wheel) |
|---|---|
| APP | `results/monitoring/models/APP_demo_logistic_regression.joblib` |
| HDFS | `results/phase1/models/HDFS_quick_linear_svm.joblib` |
| BGL | `results/phase1/models/BGL_quick_decision_tree.joblib` |

**APP caveat:** synthetic demo model for controlled app-log windows — **not** production incident diagnosis.

Prefer **absolute** `model_path` values. Relative artifact entries resolve against `AETHER_ROOT` or the config’s project root — not an unrelated CWD.

---

## 7. Architecture (0.4)

```
pip install [all]
        │
        ▼
aether init / AETHER_ROOT ──► configs + external .joblib
        │
        ▼
aether start ──► uvicorn (FastAPI MonitoringPipeline)
                    │
                    ├── /health /status /alerts /infer /rca …   (API)
                    └── / + /assets/*   (packaged React console)
```

SDK path remains independent: `from aether import Aether, AetherConfig` with no FastAPI required.

---

## 8. API overview (SDK)

| Method | Purpose |
|---|---|
| `start()` | Load model; init buffers and alert store |
| `process` / `process_batch` | Ingest records |
| `stats()` / `list_alerts` / `recent_predictions` | Observe |
| `stop()` | Release resources |

Exceptions: `AetherError`, `AetherConfigError`, `AetherNotStartedError`, `AetherModelError`, `AetherSchemaError`, `AetherStateError`.

---

## 9. Security (honest defaults)

| Setting | Default |
|---|---|
| Bind | `127.0.0.1` |
| Auth | Off on loopback until keys set; **forced** for non-loopback |
| CORS | Explicit localhost origins (no `*`) |
| Secrets | Environment only — never in the UI bundle |
| Console API key | Optional browser `localStorage` (`Settings`) |

**Production gaps:** no multi-tenant isolation claim, OTLP ingest is loopback-oriented, RCA/AI are experimental, dual-write Postgres is optional, and upload/ops hardening is documented under `docs/` — treat public exposure as operator responsibility.

---

## 10. Troubleshooting

| Symptom | Fix |
|---|---|
| `Monitoring config not found` | `aether init` and set `AETHER_ROOT` |
| Model artifact missing | Train/copy `.joblib`; use absolute path |
| Console missing after install | Use a 0.4+ wheel; rebuild with `python scripts/build_console.py` |
| `ModuleNotFoundError: fastapi` | `pip install "aether-observability[all]"` |
| Port in use | `aether status` / change `--port` or stop the other process |
| Auth 401 in UI | Settings → API key, or disable auth on loopback |

---

## 11. Development checks

```bash
pip install -e ".[dev]"
python scripts/build_console.py
pytest -q
ruff check src tests
python -m build
python -m twine check dist/*
```

Do **not** upload to TestPyPI/PyPI from this checklist unless explicitly requested.

| Item | Value |
|---|---|
| PyPI | https://pypi.org/project/aether-observability/ |
| Distribution | `aether-observability` |
| Import | `aether` |
| Version | **0.4.0** |
| License | **MIT** |

Advanced topics: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md), [docs/SECURITY.md](docs/SECURITY.md), [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md), [docs/LIMITATIONS.md](docs/LIMITATIONS.md).
