nthlayer 0.1.0a20

NthLayer - The Missing Layer of Reliability

NthLayer

Reliability as code. Pure compiler.

Define reliability requirements in a manifest. Generate dashboards, alerts, SLOs, and documentation — deterministically, every time.

TL;DR

pip install nthlayer
nthlayer init
nthlayer apply service.yaml

---

⚠️ The Problem

Reliability decisions happen too late. Teams set SLOs in isolation, deploy without checking error budgets, and discover missing metrics during incidents. Dashboards are inconsistent. Alerts are copy-pasted. Nobody validates whether a 99.99% target is even achievable given dependencies.

💡 The Solution

NthLayer is a pure compiler for reliability infrastructure. Write a manifest, get artifacts:

service.yaml → validate → apply
                  │          │
                  │          └── Grafana dashboards, Prometheus alerts,
                  │              recording rules, SLOs, PagerDuty config,
                  │              Backstage entities, service docs
                  │
                  └── SLO feasible? Dependencies support it? Metrics exist?
                      Policies pass? Ceiling valid?

NthLayer generates. nthlayer-observe enforces at runtime.

---

⚡ Core Features

Artifact Generation

Generate dashboards, alerts, and SLOs from a single spec.

$ nthlayer apply service.yaml

Generated:
  → dashboard.json (Grafana)
  → alerts.yaml (Prometheus)
  → recording-rules.yaml (Prometheus)
  → slos.yaml (OpenSLO)
  → backstage.json (Backstage entity)

Dependency-Aware SLO Validation

Your SLO ceiling is your weakest dependency chain. NthLayer calculates it.

$ nthlayer validate-slo payment-api

Target: 99.99% availability
Dependencies:
  → postgresql (99.95%)
  → redis (99.99%)
  → user-service (99.9%)

Serial availability: 99.84%
✗ INFEASIBLE: Target exceeds dependency ceiling by 0.15%

Recommendation: Reduce target to 99.8% or improve user-service SLO

Metric Recommendations

Enforce OpenTelemetry conventions. Know what's missing before production.

$ nthlayer recommend-metrics payment-api

Required (SLO-critical):
  ✓ http.server.request.duration    FOUND
  ✗ http.server.active_requests     MISSING

Run with --show-code for instrumentation examples.

Monte Carlo SLO Simulation

Model failure scenarios before they happen.

$ nthlayer simulate service.yaml --scenarios 10000

Monte Carlo Simulation (10,000 runs)
  SLO: availability ≥ 99.9%
  Result: 94.2% of scenarios meet target
  P50 availability: 99.95%
  P99 availability: 99.82%
  Risk: 5.8% chance of SLO breach in 30d window

Topology Export

Export dependency graphs for correlation engines.

$ nthlayer topology export service.yaml --format json
$ nthlayer topology export service.yaml --format mermaid
$ nthlayer topology export service.yaml --format dot

Policy Validation

Enforce organizational standards at build time.

$ nthlayer validate service.yaml --policies policies.yaml

✓ required_fields: ownership.runbook present
✗ tier_constraint: critical services require deployment gates
✓ dependency_rule: all critical deps have SLOs

---

🚀 Quick Start

# Install
pip install nthlayer

# Create a service spec
nthlayer init

# Validate and generate
nthlayer apply service.yaml

Minimal service.yaml

name: payment-api
tier: critical
type: api
team: payments

dependencies:
  - postgresql
  - redis

NthLayer also supports the OpenSRM format (apiVersion: opensrm/v1) for contracts, deployment gates, and more. See full spec reference for all options.

---

🔄 CI/CD Integration

# GitHub Actions
- name: Validate reliability
  run: |
    nthlayer validate service.yaml
    nthlayer validate-slo service.yaml
    nthlayer apply service.yaml --output-dir generated/

For runtime enforcement (deployment gates, drift detection, error budget checks), use nthlayer-observe:

- name: Gate deployment
  run: |
    nthlayer-observe check-deploy payment-api

Works with: GitHub Actions, GitLab CI, ArgoCD, Tekton, Jenkins

---

🎯 How It's Different

Traditional Approach	NthLayer
Set SLOs in isolation	Validate against dependency chains
Manual dashboard creation	Generate from spec
Copy-paste alerts	593+ alert templates, auto-selected
Discover missing metrics in incidents	Enforce before deployment
"Is this ready?" = opinion	"Is this ready?" = deterministic check

---

📚 Documentation

Full Documentation - Comprehensive guides and reference.

Guide	Description
Quick Start	Get running in 5 minutes
Dependency Discovery	Automatic dependency mapping
CI/CD Integration	Pipeline setup
CLI Reference	All commands

---

🗺️ Roadmap

Generate (this repo)

• Artifact generation (dashboards, alerts, SLOs, recording rules, Loki alerts)
• Dependency-aware SLO validation
• Metric recommendations (OpenTelemetry conventions)
• Monte Carlo SLO simulation
• Policy validation (build-time)
• Topology export (JSON, Mermaid, DOT)
• OpenSRM manifest format (opensrm/v1)
• Identity resolution & ownership
• Backstage entity generation
• Service documentation generation
• CI/CD GitHub Action
• Agentic inference (nthlayer infer)
• MCP server integration
• Backstage plugin

Observe (nthlayer-observe)

• Deployment gates (check-deploy)
• Drift detection (drift)
• Error budget collection (collect)
• Portfolio view (portfolio)
• Reliability scorecard (scorecard)
• Blast radius analysis (blast-radius)
• Dependency discovery (discover, dependencies)
• Runtime verification (verify)

---

Agentic Inference (Planned)

nthlayer infer will use a model to analyse a codebase and propose an OpenSRM manifest for it. The model examines the code, identifies services, infers appropriate SLO targets, and generates a draft service.reliability.yaml that NthLayer then validates and generates artifacts from.

This follows Zero Framework Cognition: the model provides judgment (what SLOs does this service need?), and NthLayer provides transport (validate the manifest, generate the monitoring artifacts). Clean boundary between reasoning and deterministic transformation.

---

OpenSRM Ecosystem

NthLayer is one component in the OpenSRM ecosystem. Each component solves a complete problem independently, and they compose when used together through shared OpenSRM manifests and OTel telemetry conventions.

                        ┌─────────────────────────┐
                        │     OpenSRM Manifest     │
                        │  (the shared contract)   │
                        └────────────┬────────────┘
                                     │
                    reads            │           reads
               ┌─────────────┬──────┴──────┬─────────────┐
               ▼             ▼             ▼             ▼
         ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
         │ MEASURE  │ │>NTHLAYER<│ │CORRELATE │ │ RESPOND  │
         │          │ │          │ │          │ │          │
         │ quality  │ │ generate │ │correlate │ │ incident │
         │+govern   │ │ monitoring│ │ signals  │ │ response │
         │+cost     │ │          │ │          │ │          │
         └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
              │             │             │             │
              └─────────────┴──────┬──────┴─────────────┘
                                   ▼
                     ┌──────────────────────────┐
                     │      Verdict Store       │
                     │  (shared data substrate) │
                     │ create · resolve · link  │
                     │ accuracy · gaming-check  │
                     └────────────┬─────────────┘
                                  │ OTel side-effects
                                  ▼
                     ┌──────────────────────────┐
                     │    OTel Collector /      │
                     │   Prometheus / Grafana   │
                     └──────────────────────────┘

              Learning loop (post-incident):
              nthlayer-respond findings → manifest updates
              → NthLayer regenerates → nthlayer-measure
              refines → nthlayer-correlate improves → OpenSRM

How NthLayer fits in:

• NthLayer reads OpenSRM manifests and generates the monitoring infrastructure (Prometheus rules, Grafana dashboards, PagerDuty config) that the rest of the ecosystem relies on
• Verdict operations emit OTel side-effects (gen_ai.decision.*, gen_ai.override.*) that flow into Prometheus. NthLayer generates dashboards for these metrics alongside service dashboards — NthLayer reads from Prometheus, not the Verdict Store directly.
• NthLayer exports service topology that nthlayer-correlate uses for topology-aware signal correlation
• nthlayer-respond's post-incident findings feed back into NthLayer as rule refinements (alerts that should have fired earlier or didn't fire at all)

Each component works alone. Someone who just needs reliability-as-code adopts NthLayer without needing the rest of the ecosystem.

Component	What it does	Link
OpenSRM	Specification for declaring service reliability requirements	OpenSRM
NthLayer	Generate monitoring infrastructure from manifests (this repo)	nthlayer
nthlayer-observe	Runtime enforcement: deployment gates, drift detection, error budgets	nthlayer-observe
nthlayer-learn	Data primitive for recording AI judgments and measuring correctness	nthlayer-learn
nthlayer-measure	Quality measurement and governance for AI agents	nthlayer-measure
nthlayer-correlate	Situational awareness through signal correlation	nthlayer-correlate
nthlayer-respond	Multi-agent incident response	nthlayer-respond

---

🤝 Contributing

# Install uv (https://docs.astral.sh/uv/)
curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/rsionnach/nthlayer.git
cd nthlayer
make setup    # Install deps, start services
make test     # Run tests

See CONTRIBUTING.md for details.

---

📄 License

MIT - See LICENSE.txt

---

🙏 Acknowledgments

Built on grafana-foundation-sdk, awesome-prometheus-alerts, pint, and OpenSLO. Inspired by Sloth and autograf.