Metadata-Version: 2.4
Name: spero
Version: 0.4.0
Summary: Self-healing supervision agent for Linux hosts and Kubernetes.
Project-URL: Homepage, https://github.com/altikva/spero
Project-URL: Repository, https://github.com/altikva/spero
Author: Joy Ndjama
License-Expression: MIT AND CC-BY-NC-SA-4.0
License-File: LICENSE
License-File: NOTICE
Keywords: aiops,kubernetes,monitoring,self-healing,sre,supervision
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: alembic>=1.13
Requires-Dist: apscheduler<4,>=3.10
Requires-Dist: asyncssh>=2.20
Requires-Dist: cryptography>=42.0
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.7
Requires-Dist: sqlalchemy>=2.0.30
Requires-Dist: typer>=0.15
Requires-Dist: uvicorn[standard]>=0.30
Requires-Dist: watchdog>=5.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.69; extra == 'ai'
Requires-Dist: rank-bm25>=0.2; extra == 'ai'
Provides-Extra: certs
Requires-Dist: cryptography>=42; extra == 'certs'
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.5; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: k8s
Requires-Dist: kubernetes>=31.0; extra == 'k8s'
Provides-Extra: mcp
Requires-Dist: fastmcp<3,>=2.8; extra == 'mcp'
Provides-Extra: tui
Requires-Dist: textual>=0.60; extra == 'tui'
Description-Content-Type: text/markdown

<!--
# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
# __creation__ = 2026-06-03
# __author__ = "jndjama (Joy Ndjama)"
# __copyright__ = "Copyright 2026 ALTIKVA."
# __licence__ = "MIT & CC BY-NC-SA (https://www.altikva.com/licenses/LICENSE-1.0)"
# -#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#-#
# Description: Project README: what Spero is, its concepts, quickstart, and roadmap.
-->

```
 ___ _ __   ___ _ __ ___
/ __| '_ \ / _ \ '__/ _ \
\__ \ |_) |  __/ | | (_) |
|___/ .__/ \___|_|  \___/
    |_|
```

**Self-healing supervision agent for Linux hosts and Kubernetes.**

Spero watches the things you run — processes, services, disks, workloads — notices
when they break, and heals them under policy-governed autonomy. It sits between a
single-host tool like Monit and a full Prometheus + Alertmanager + Ansible stack:
lightweight, agent-based, cluster-aware, with an AI layer for prediction,
root-cause, and policy-gated remediation.

Shipped under [Altikva](https://altikva.com).

> Status: pre-alpha, but the spine is complete. Spero supervises and heals Linux
> hosts (local + asyncssh) and Kubernetes (kubectl) through one engine, with an AI
> layer for prediction, root-cause, natural-language queries, and agentic
> (policy-gated) remediation. 91 tests, ruff + mypy clean.

## Concepts

Spero is built on four seams so it spans hosts today and Kubernetes next without
re-architecting:

| Seam | Question | Examples |
|------|----------|----------|
| **Provider** | where things run | local, SSH host, Kubernetes |
| **Probe** | how you know it is healthy | process, systemd, port, disk, pod-ready |
| **Remediation** | what to do about it | restart, respawn, rotate, rollout, scale |
| **Policy** | the declared intent | YAML: target → probe → remediations + autonomy |

Remediations carry an **autonomy** level — `suggest`, `gated`, or `auto` — so
low-risk healing happens on its own while high-risk actions wait for a human.

## Install

```bash
pip install spero            # or: uv pip install spero
pip install "spero[ai]"      # add the Claude-backed AI layer
pip install "spero[k8s]"     # add the Kubernetes provider deps
```

## Quickstart

```bash
spero status                       # show targets from policies/example.yaml
spero run                          # run one supervision cycle
spero watch                        # supervise continuously (each target on its interval)
spero watch --ai-approve           # agentic: the model decides gated remediations
spero heal nginx                   # probe one target, walk its remediations interactively
spero ask "what flapped today?"    # natural-language query over the event history
spero serve                        # run the control-plane API on :8800
```

## Data egress and privacy

With `ANTHROPIC_API_KEY` set, `spero ask`, `spero diagnose`, and `--ai-approve`
send text to Anthropic's API: the question, target names, remediation params, and
recorded event details (which can include command output). Event details are also
stored in the local sqlite database. With no key, spero uses the `NullLLM` fallback
and nothing leaves the host. To scrub likely secrets/PII from event text before it
is sent to the model, set `SPERO_REDACT_EVENTS=1` (best-effort; see
`src/spero/ai/redact.py`). The control-plane endpoints that expose object YAML and
pod logs are token-guarded; see `deploy/k8s/README.md`.

## From source

```bash
git clone https://github.com/altikva/spero && cd spero
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest                             # run the suite
```

## License

Spero is released under the **ALTIKVA Dual License v1.0**
([MIT](./LICENSE) and [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)),
SPDX `MIT AND CC-BY-NC-SA-4.0`. See [LICENSE](./LICENSE).
