Metadata-Version: 2.5
Name: iowap-node
Version: 2.3.20
Summary: IOWAP Node Framework — daemon, CLI, and handler runner for distributed agent nodes
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.7
Requires-Dist: python-multipart>=0.0.18
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: zeroconf>=0.63
Description-Content-Type: text/markdown

# iowap-node

**IOWAP Node Framework — Build your own node in the IOWAP ecosystem**

> **THIS IS THE REPO YOU WANT** if you want to run a node. Clone this, configure your capabilities, and join the network.

The node framework provides everything you need to register, heartbeat, claim tasks, and run handlers. Nodes are the workers — they advertise what they can do and execute tasks when matched.

## Quick Start (Linux)

```bash
curl -fsSL https://raw.githubusercontent.com/iowap-org/iowap-node/main/install.sh | bash
```

Manuell (jede Plattform):

```bash
git clone https://github.com/iowap-org/iowap-node.git
cd iowap-node
pip install -e .
cp relay_config.json.example ~/.relay/relay_config.json
# edit ~/.relay/relay_config.json
node-cli node register
node-cli capabilities publish default
```

## What You Can Build

A node is just a process that:

1. **Heartbeats** its capabilities to a relay server (what can I do?)
2. **Claims tasks** that match its capabilities (I'll take this)
3. **Runs handlers** — scripts or programs — to execute the work
4. **Completes tasks** with results

Your capabilities are defined in a `node.yaml`:

```yaml
node_name: "my-notifier"
node_description: "Sends push notifications"
capabilities:
  notification.send:
    description: "Send a push notification to my phone"
    type: script
    input_schema:
      fields:
        - name: title
          type: string
          required: true
          description: "Notification title"
        - name: body
          type: string
          required: true
          description: "Notification body"
        - name: priority
          type: string
          required: false
          description: "low / normal / high"
```

Just write a handler script that reads the JSON payload from stdin, calls your push service, and writes the result to stdout. That's it — the node framework handles the rest.

## Components

| Component | Description |
|-----------|-------------|
| `node-cli` | CLI tool — register, manage, submit tasks, list nodes |
| `node-daemon` | Event-driven worker — listens for tasks via SSE, runs handlers |
| `relay_client` | HTTP client library for relay API |
| `handler_runner` | Execute custom handlers with stdin/stdout contract |
| `node_config` | Capability/configuration management |

## CLI Reference

```bash
node-cli register                  # Register with a relay server
node-cli capabilities server       # List server-known capabilities
node-cli capabilities publish      # Publish your capabilities
node-cli task submit <capability>  # Submit a task
node-cli task wait <id>            # Wait for task completion
node-cli node list                 # List registered nodes
node-cli node info <id>            # Node details
node-cli daemon                    # Start the daemon (foreground)
node-cli bridge upload <file>      # Upload via bridge route
node-cli bridge download <url>     # Download via bridge route
```

## Docker

A base Docker image is available for containerized nodes:

```bash
docker pull ghcr.io/iowap-org/iowap-node:latest
```

See `docker/nodes/base/` for the Dockerfile.

## Docs

Full documentation in [iowap-org/iowap-docs](https://github.com/iowap-org/iowap-docs):

- [getting-started.md](https://github.com/iowap-org/iowap-docs/blob/main/getting-started.md) — first steps
- [node/setup.md](https://github.com/iowap-org/iowap-docs/blob/main/node/setup.md) — node setup
- [node/cli.md](https://github.com/iowap-org/iowap-docs/blob/main/node/cli.md) — full CLI reference
- [node/capabilities.md](https://github.com/iowap-org/iowap-docs/blob/main/node/capabilities.md) — capability definitions
- [federation/concept.md](https://github.com/iowap-org/iowap-docs/blob/main/federation/concept.md) — cross-relay federation

## License

MIT — see [LICENSE](LICENSE).
