Metadata-Version: 2.4
Name: spero
Version: 0.1.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: 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'
Description-Content-Type: text/markdown

# Spero

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
```

## 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).
