Metadata-Version: 2.4
Name: workpeg
Version: 0.5.2
Summary: Workpeg function runtime and SDK
Author-email: Workpeg <support@workpeg.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/workpeg/workpeg-sdk
Project-URL: Repository, https://developers.workpeg.com
Keywords: workpeg,serverless,functions,runtime
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# Workpeg SDK

Python SDK and CLI for building Workpeg Pegs and execution workloads.

Workpeg is a platform for developing portable micro-apps called Pegs. Pegs can be packaged, executed, distributed through the PegStore, and integrated into the broader Workpeg ecosystem.

The SDK currently focuses on function-based Peg development and local runtime tooling, while the CLI architecture is designed to expand into additional capabilities such as client applications, Peg packaging, registry tooling, runtime orchestration, and deployment infrastructure.

## Current capabilities

* Peg scaffolding
* Function-based execution model
* Fast local runtime
* Persistent Docker runtime
* Docker image packaging
* Registry submission
* Runtime configuration
* Warm container execution

## Repository

[Workpeg SDK Repository](https://gitlab.com/workpeg/workpeg-sdk?utm_source=chatgpt.com)

---

# Installation

Install from PyPI:

```bash id="0d2m52"
pip install workpeg
```

Or install locally from source:

```bash id="4d9q9q"
pip install -e .
```

Verify installation:

```bash id="56gg0t"
workpeg --version
```

---

# CLI Architecture

Workpeg uses a namespace-oriented CLI inspired by tools like Docker.

Current namespace:

```bash id="m0u9jj"
workpeg function ...
```

Future namespaces may include:

```bash id="8itvsl"
workpeg client ...
workpeg peg ...
workpeg registry ...
workpeg runtime ...
```

Get help:

```bash id="q3x8r2"
workpeg --help
workpeg function --help
```

---

# Quick Start

## Create a Function Peg

Create a new function project:

```bash id="kcnw5d"
workpeg function new hello
```

Generated structure:

```text id="v6m8d4"
hello/
├── app/
│   ├── __init__.py
│   └── main.py
├── tests/
├── Dockerfile
├── requirements.txt
├── workpeg.json
└── README.md
```

Example function:

```python id="h6e3xs"
def main(context, payload):
    return {
        "message": "Hello from Workpeg",
        "payload": payload,
    }
```

---

# Fast Local Runtime

For rapid iteration without Docker:

```bash id="rrl4su"
echo '{"context": {}, "payload": {"name":"world"}}' \
  | workpeg function runtime
```

Example response:

```json id="uohm9u"
{
  "status": "success",
  "result": {
    "message": "Hello from Workpeg",
    "payload": {
      "name": "world"
    }
  }
}
```

---

# Persistent Runtime Server

Run the runtime as a warm HTTP server:

```bash id="1n1n3x"
workpeg function runtime --server
```

Default endpoint:

```text id="07ubrq"
http://0.0.0.0:8000
```

Invoke:

```bash id="4z1s1l"
curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{"context": {}, "payload": {"hello":"world"}}'
```

Health check:

```bash id="lc3bxr"
curl http://localhost:8000/healthz
```

---

# Build Docker Image

Build a Peg runtime image:

```bash id="l8z59k"
workpeg function build
```

Specify custom tag:

```bash id="ofm9pp"
workpeg function build --tag my-image
```

The build process produces a portable runtime container for the Peg.

---

# Run Peg Runtime (Docker)

Run a warm containerized runtime:

```bash id="rbvt3p"
workpeg function run --with docker
```

This:

* Builds the image (unless disabled)
* Starts a persistent runtime container
* Exposes HTTP endpoints
* Enables warm execution

Default endpoint:

```text id="ghp23n"
http://localhost:8000
```

---

# Docker Networking

Attach runtimes to a Docker network:

```bash id="2rx4ji"
workpeg function run \
  --with docker \
  --network workpeg_net
```

Useful for inter-Peg communication and local ecosystem development:

```text id="pwnmql"
http://peg-name:8000
```

This enables multiple Peg runtimes to coexist without port collisions.

---

# Detached Warm Runtime Model

The Docker runtime uses persistent detached containers instead of one-shot execution.

This enables:

* Warm execution
* Faster repeated invocations
* Health monitoring
* Automatic restarts
* Internal networking
* Future orchestration support

Example execution model:

```text id="z3q4z1"
Function → Runtime Container → Peg → PegStore
```

---

# Runtime Backends

Workpeg supports multiple execution backends.

| Runtime | Purpose                     | Status    |
| ------- | --------------------------- | --------- |
| docker  | Local Peg development       | Available |
| cracker | Firecracker microVM runtime | Planned   |

Select backend:

```bash id="f94kq8"
workpeg function run --with docker
```

Runtime resolution order:

1. CLI flag
2. `workpeg.json`
3. Fallback default (`cracker`)

---

# Configuration

Optional project configuration:

```text id="u2pq39"
workpeg.json
```

Example:

```json id="9cv47i"
{
  "runtime": {
    "default": "docker",
    "docker": {
      "port": 8000,
      "network": "workpeg_net",
      "restart": "unless-stopped"
    }
  },
  "build": {
    "image": "my-custom-image"
  },
  "function": {
    "entrypoint": "app.main:main"
  }
}
```

---

# Function Contract

Functions implement:

```python id="9a3e3r"
def main(context: dict, payload: dict):
    return {...}
```

Input:

```json id="xgcw6e"
{
  "context": {...},
  "payload": {...}
}
```

Success output:

```json id="zptc4l"
{
  "status": "success",
  "result": {...}
}
```

Error output:

```json id="c8z1k6"
{
  "status": "error",
  "error_type": "...",
  "error": "..."
}
```

---

# Entrypoint

Default entrypoint:

```text id="e0nbql"
app.main:main
```

Override:

```bash id="v42ihq"
FUNCTION_ENTRYPOINT=app.main:handler \
  workpeg function runtime
```

---

# Docker Requirements

Required for:

```bash id="p7wvdn"
workpeg function build
workpeg function run --with docker
```

Requirements:

* Docker installed
* Docker daemon running
* Docker CLI available on PATH

When running inside another container:

```bash id="qho4i4"
-v /var/run/docker.sock:/var/run/docker.sock
```

---

# Philosophy

Workpeg is designed around composable executable applications.

Core progression:

```text id="i8n38r"
Function → Runtime → Peg → PegStore → Ecosystem
```

* Functions provide isolated execution units
* Pegs package functionality into portable micro-apps
* PegStore enables distribution
* Workpeg provides the runtime and orchestration foundation

The long-term direction is a platform where developers can build, distribute, and execute intelligent applications inside a unified ecosystem.

---

# Roadmap

Planned:

* Firecracker runtime backend
* Persistent microVM execution
* PegStore tooling
* Peg packaging workflows
* Client app tooling
* Runtime orchestration
* Streaming execution
* Registry approvals & governance
* Distributed runtime scheduling

---

# License

MIT License
