Metadata-Version: 2.4
Name: seqpulse
Version: 0.3.0
Summary: SeqPulse SDK for metrics endpoint instrumentation and HMAC validation
Author: Nassir
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: FastAPI
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9.0
Requires-Dist: starlette>=0.36.0
Dynamic: license-file

# seqpulse (Python SDK)

SeqPulse Python SDK couvre deux usages:

- Runtime application: instrumentation HTTP + endpoint metrics + validation HMAC v2
- CI/CD integration: client `trigger/finish` pour orchestrer un deployment SeqPulse

## Install

```bash
pip install seqpulse
```

## Runtime (FastAPI)

```python
from fastapi import FastAPI
from seqpulse import SeqPulse

app = FastAPI()

seqpulse = SeqPulse(
    endpoint="/seqpulse-metrics",
    hmac_enabled=True,
    hmac_secret="hmac_xxx",
)

app.middleware("http")(seqpulse.middleware())
```

`GET /seqpulse-metrics` returns:

```json
{
  "metrics": {
    "requests_per_sec": 0.25,
    "latency_p95": 31.221,
    "error_rate": 0,
    "cpu_usage": 0.42,
    "memory_usage": 0.18
  }
}
```

## CI/CD client (trigger/finish)

```python
from seqpulse import create_ci_client

client = create_ci_client(
    base_url="https://api.seqpulse.dev",
    api_key="sp_xxx",
    metrics_endpoint="https://your-app.example.com/seqpulse-metrics",
    env="prod",
    non_blocking=True,
)

trigger = client.trigger(branch="main")

# Deploy your app here...
deploy_succeeded = True

if trigger.get("ok") and trigger.get("deployment_id"):
    client.finish(
        deployment_id=trigger["deployment_id"],
        result="success" if deploy_succeeded else "failed",
    )
```

### CI behavior

- `non_blocking=True` (default): retourne un resultat skipped/error, sans lever d'exception.
- `non_blocking=False`: leve une exception sur erreur API/config.
- helpers inclus: `build_ci_idempotency_key()`, `infer_result_from_pipeline_status()`.

## Compatibility note

Cette evolution **n'ecrase pas** le SDK runtime actuel:

- l'endpoint `/seqpulse-metrics` reste le meme
- la logique HMAC runtime reste la meme
- le client CI est ajoute en couche supplementaire

## Local smoke test

```bash
python scripts/smoke.py
```
