Metadata-Version: 2.4
Name: halyn
Version: 0.2.1
Summary: Halyn — NRP control plane with domain-scoped authorization.
Author-email: Elmadani SALKA <Elmadani.SALKA@proton.me>
License: MIT
Project-URL: Homepage, https://github.com/ElmadaniS/halyn
Project-URL: Repository, https://github.com/ElmadaniS/halyn
Project-URL: Issues, https://github.com/ElmadaniS/halyn/issues
Keywords: ai,browser,robotics,iot,mcp,nrp,llm,infrastructure,devops
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nrprotocol>=0.1.0
Requires-Dist: aiohttp>=3.9
Provides-Extra: enterprise
Requires-Dist: grpcio>=1.60; extra == "enterprise"
Requires-Dist: psycopg2-binary; extra == "enterprise"
Requires-Dist: redis; extra == "enterprise"
Provides-Extra: robotics
Requires-Dist: rclpy; extra == "robotics"
Requires-Dist: unitree-sdk2py; extra == "robotics"
Provides-Extra: iot
Requires-Dist: paho-mqtt; extra == "iot"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="logo.svg" width="80" alt="Halyn">

# Halyn

### NRP Control Plane

**Connect any device to any LLM through NRP.**

NRP control plane with domain-scoped authorization.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10+-green.svg)](https://python.org)
[![Tests](https://img.shields.io/badge/Tests-48%20passed-brightgreen.svg)]()
[![NRP](https://img.shields.io/badge/Protocol-NRP-orange.svg)](https://github.com/ElmadaniS/nrp)

</div>

---

```
you:    "How's the factory?"

halyn:  All 12 arms running. Arm-7 joint 3 is 12°C above normal.
        Soil moisture in the north field dropped to 18%.
        3 urgent emails. Hetzner invoice due tomorrow.
        Want me to handle any of these?
```

## What It Does

Halyn connects AI to:

| Domain | Examples |
|--------|----------|
| **Servers** | Deploy, monitor, fix, scale |
| **Robots** | Move, pick, navigate, patrol |
| **Sensors** | Temperature, humidity, soil, air |
| **APIs** | Stripe, GitHub, Slack — any REST/GraphQL |
| **Factories** | PLCs, SCADA, OPC-UA, Modbus |
| **Smart Home** | Lights, climate, security |
| **Vehicles** | Navigate, charge, maintain |
| **Drones** | Survey, photograph, deliver |

One protocol. One conversation. Everything.

## Quick Start

```bash
pip install halyn

halyn scan       # discover your world
halyn connect    # plug your LLM
halyn serve      # start running
```

## Any LLM

```yaml
# halyn.yml
llm:
  provider: claude        # or: openai, ollama, huggingface, vllm
  model: claude-sonnet-4-20250514
```

Halyn doesn't lock you in. Claude today. Local Ollama tomorrow. Same nodes. Same drivers. Same safety.

## Human Always in Control

5 autonomy levels. Per domain. Per node. Per hour.

| Level | Name | Behavior |
|-------|------|----------|
| 0 | **Manual** | AI proposes. You approve every action. |
| 1 | **Supervised** | AI reads alone. Asks before acting. |
| 2 | **Guided** | Safe actions alone. Dangerous = confirm. |
| 3 | **Autonomous** | Does everything. You can interrupt anytime. |
| 4 | **Full Auto** | Handles routine. Reports daily. |

```yaml
# halyn.yml
domains:
  physical:
    level: 1                              # supervised
    nodes: [robot/*, drone/*]
    confirm: [move, pick, deploy]

  financial:
    level: 0                              # manual — confirm everything
    nodes: [finance/*, bank/*]
    blocked: [delete]

  monitoring:
    level: 4                              # full auto
    nodes: [sensor/*, monitor/*]

  infrastructure:
    level: 2                              # guided
    nodes: [server/*, cloud/*]
    confirm: [restart, deploy, delete]
```

Your banking requires approval for every action. Your sensors run on autopilot. Your servers auto-handle safe ops but confirm deploys. You set the rails once. The AI rides them.

## Security

Not optional. Not a feature. The foundation.

| Layer | What It Does |
|-------|-------------|
| **Auth** | API key with timing-safe HMAC |
| **Autonomy** | 5 levels per domain, rate limiting |
| **Shield** | Per-node safety rules from NRP |
| **Sanitizer** | Injection, traversal, overflow protection |
| **Audit** | SHA-256 hash-chain on disk, tamper-detectable |
| **Watchdog** | Health monitoring, failsafe on crash |
| **Redaction** | No internal paths or secrets in errors |

If Halyn crashes, nodes enter safe state automatically.

The audit trail is a hash chain. Tamper with one entry and the chain breaks. Every action records: who asked, which AI decided, what reasoning, what result, which domain policy authorized it.

## Architecture

```
Any LLM
  │  MCP
  ▼
Halyn Control Plane
  │  ┌─ Autonomy (5 levels)
  │  ├─ Audit (SHA-256 chain)
  │  ├─ Watchdog (failsafe)
  │  ├─ Auth + Sanitizer
  │  └─ Memory (SQLite + FTS5)
  │
  │  NRP (Node Reach Protocol)
  │
  ├──→ SSH (servers)
  ├──→ Docker (containers)
  ├──→ Chrome CDP (browsers)
  ├──→ ROS2 (robots)
  ├──→ Unitree (humanoids)
  ├──→ MQTT (IoT sensors)
  ├──→ OPC-UA (industrial PLCs)
  ├──→ HTTP Auto (any API — auto-introspected)
  └──→ Your driver (~100 lines)
```

## HTTP Auto-Introspection

Point Halyn at any API. It reads the OpenAPI/GraphQL spec. Generates the manifest. Creates the tools. Automatically.

```yaml
nodes:
  - id: nrp://cloud/api/stripe
    driver: http_auto
    base_url: https://api.stripe.com/v1
    auth_token: Bearer ${STRIPE_API_KEY}

  - id: nrp://cloud/api/github
    driver: http_auto
    base_url: https://api.github.com
    auth_token: Bearer ${GITHUB_TOKEN}
```

Any API in the world becomes an NRP node. Zero custom code.

## Docker

```bash
docker compose up -d
```

```yaml
# docker-compose.yml included — non-root, healthcheck, resource limits
```

## Stats

| Metric | Value |
|--------|-------|
| Source lines | ~5,200 |
| Drivers | 9 |
| LLM connectors | 5 (Claude, GPT, Ollama, HF, vLLM) |
| Tests | 48 passed, 0 failed |
| Dependencies | 1 (aiohttp) |
| Docker image | ~150MB |
| MCP native | Yes (Claude.ai direct) |
| Tested on | Real hardware across 3 countries |

## Built on NRP

Halyn implements the [Node Reach Protocol](https://github.com/ElmadaniS/nrp) — the universal standard for AI-to-world control. Any NRP-compatible device works with Halyn automatically.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Security

See [SECURITY.md](SECURITY.md). Report vulnerabilities to Elmadani.SALKA@proton.me.

## License

MIT

## Author

**Elmadani SALKA**
