Metadata-Version: 2.4
Name: flux-registry
Version: 0.1.0
Summary: FLUX Registry — Pre-compiled agent policies, installable and runnable
Author: SuperInstance
License: MIT
Project-URL: Homepage, https://github.com/SuperInstance/flux-registry
Project-URL: Repository, https://github.com/SuperInstance/flux-registry
Keywords: flux,vm,policy,registry,agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# FLUX Registry

> **npm for agent policies.** Pre-compiled FLUX bytecode, installable and runnable.

Pre-compiled agent policies, installable and runnable. The registry is a static
JSON index on GitHub — no server required. The CLI downloads from
`raw.githubusercontent.com` and caches policies locally in `~/.flux/policies/`.

## Install

```bash
pip install flux-registry
```

## Quick Start

```bash
# Browse available policies
flux list --remote

# Install a policy
flux install deadband-controller

# Run it
flux run deadband-controller --input temperature=72
# Output: action=idle

flux run deadband-controller --input temperature=80
# Output: action=cool

flux run deadband-controller --input temperature=60
# Output: action=heat

# Get details
flux info deadband-controller
```

## Commands

| Command | Description |
|---------|-------------|
| `flux install <policy>` | Install a policy from the remote registry |
| `flux list [--remote]` | List installed (or remote) policies |
| `flux info <policy>` | Show detailed metadata, inputs, outputs |
| `flux run <policy> --input K=V` | Execute a policy with given inputs |
| `flux remove <policy>` | Remove an installed policy |
| `flux update-index` | Refresh the local registry cache |

## Available Policies

| Policy | Description | Inputs | Outputs |
|--------|-------------|--------|---------|
| `deadband-controller` | Thermostat with hysteresis — AC at 75°, heat at 65° | temperature (°F) | action: idle/cool/heat |
| `budget-tracker` | Conservation budget enforcement — track resource depletion | cost, budget | remaining, status: ok/exceeded |
| `rate-limiter` | Token bucket rate limiting — check and consume tokens | tokens, cost | remaining, allowed: denied/allowed |
| `security-scanner` | Basic vulnerability detection — threshold-based policy check | value, threshold | verdict: safe/violation, severity |

## Policy Format

Each policy is a JSON file containing:

```json
{
  "name": "deadband-controller",
  "version": "0.1.0",
  "description": "Thermostat deadband controller",
  "author": "SuperInstance",
  "bytecode": "<base64-encoded FLX0 binary>",
  "source": "deadband-controller.flx",
  "bytecode_hash": "sha256...",
  "bytecode_size": 32,
  "inputs": [{"name": "temperature", "type": "float", "register": "R0"}],
  "outputs": [{"name": "action", "type": "int", "register": "R1",
               "values": {"0": "idle", "1": "cool", "2": "heat"}}],
  "conservation": {"max_steps": 100, "memory_budget": 256},
  "conformance": "verified on flux-vm 0.1.0, fluxvm 0.1.0, flux-js 0.1.0",
  "tags": ["iot", "thermostat", "hvac"],
  "license": "MIT"
}
```

## Architecture

```
┌──────────────────────────────────────────────────────┐
│                   FLUX Registry                       │
│                                                       │
│  GitHub (static JSON)          Local (~/.flux/)       │
│  ┌─────────────────┐          ┌──────────────────┐   │
│  │ registry/       │  install │ policies/        │   │
│  │   index.json    │ ───────▶ │   deadband.json  │   │
│  │   deadband.json │          │   budget.json    │   │
│  │   budget.json   │          └────────┬─────────┘   │
│  │   rate-limiter  │                   │              │
│  │   security.json │          ┌────────▼─────────┐   │
│  └─────────────────┘          │   flux CLI       │   │
│                               │   ┌────────────┐ │   │
│                               │   │ Mini FLUX  │ │   │
│                               │   │ VM (built  │ │   │
│                               │   │  in)       │ │   │
│                               │   └────────────┘ │   │
│                               └──────────────────┘   │
└──────────────────────────────────────────────────────┘
```

The mini FLUX VM is built into the CLI for zero-dependency local execution.
For production use, policies can be run on any FLUX implementation:

| Runtime | Language | Install |
|---------|----------|---------|
| [flux-vm](https://pypi.org/project/flux-vm/) | Python | `pip install flux-vm` |
| [fluxvm](https://crates.io/crates/fluxvm) | Rust | `cargo add fluxvm` |
| [flux-js](https://www.npmjs.com/package/flux-js) | JavaScript | `npm install flux-js` |

All run the same bytecode — same policy, different shells.

## Conservation Guarantees

Every policy declares conservation limits:

```json
"conservation": {
  "max_steps": 100,
  "memory_budget": 256
}
```

The VM enforces these at runtime — a policy cannot exceed its step count or
memory allocation. This makes FLUX policies safe to run as untrusted code.

## Adding Policies

1. Write a policy in `.flx` source
2. Compile with `flux-compiler`
3. Create a JSON manifest with bytecode + metadata
4. Submit a PR to add it to `registry/`

## License

MIT — Same bytecode, different shells. 🦀

## Related

- [flux-vm](https://github.com/SuperInstance/flux-vm) — Stack-based constraint VM (50 opcodes)
- [flux-compiler](https://github.com/SuperInstance/flux-compiler) — Formal-methods compiler
- [flux-js](https://github.com/SuperInstance/flux-js) — JavaScript VM
- [PACKAGES.md](https://github.com/SuperInstance/SuperInstance/blob/main/PACKAGES.md) — Full package index
