Metadata-Version: 2.4
Name: workpeg
Version: 0.6.0
Summary: Workpeg function runtime and SDK
Author-email: Workpeg <support@workpeg.com>
License: MIT
Project-URL: Homepage, https://developers.workpeg.com
Project-URL: Repository, https://gitlab.com/workpeg/workpeg-sdk
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 runtime-backed micro-apps.

Workpeg is a platform for developing portable applications 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, runtime tooling, Docker packaging, and asset distribution, while the CLI architecture is designed to expand into additional capabilities such as client applications, Peg packaging, orchestration, deployment infrastructure, and registry tooling.

## Current capabilities

* Peg scaffolding
* Function-based runtime model
* Fast local runtime
* Persistent Docker runtime
* Docker image packaging
* Registry submission
* Public CDN asset uploads
* Runtime configuration
* Warm container execution
* Docker networking support

## Repository

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

---

# Installation

Install from PyPI:

```bash
pip install workpeg
```

Or install locally from source:

```bash
pip install -e .
```

Verify installation:

```bash
workpeg --version
```

---

# CLI Architecture

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

Current namespaces:

```bash
workpeg function ...
workpeg cdn ...
```

Future namespaces may include:

```bash
workpeg client ...
workpeg peg ...
workpeg registry ...
workpeg runtime ...
```

Get help:

```bash
workpeg --help
workpeg function --help
workpeg cdn --help
```

---

# Quick Start

## Create a Function Peg

Create a new function project:

```bash
workpeg function new hello
```

Generated structure:

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

Example function:

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

---

# Fast Local Runtime

For rapid iteration without Docker:

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

Example response:

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

---

# Persistent Runtime Server

Run the runtime as a warm HTTP server:

```bash
workpeg function runtime --server
```

Default endpoint:

```text
http://0.0.0.0:8000
```

Invoke:

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

Health check:

```bash
curl http://localhost:8000/healthz
```

---

# Build Docker Image

Build a Peg runtime image:

```bash
workpeg function build
```

Specify custom tag:

```bash
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
workpeg function run --with docker
```

This:

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

Default endpoint:

```text
http://localhost:8000
```

---

# Docker Networking

Attach runtimes to a Docker network:

```bash
workpeg function run \
  --with docker \
  --network workpeg_net
```

Useful for inter-Peg communication and local ecosystem development:

```text
http://peg-name:8000
```

This enables multiple Peg runtimes to coexist without port collisions.

Example:

```bash
workpeg function run \
  --with docker \
  --network workpeg_net \
  --name calendar
```

Then other containers can reach it at:

```text
http://calendar:8000
```

---

# CDN Asset Uploads

Upload public Peg assets to the CDN:

Single file:

```bash
workpeg cdn submit logo.png
```

Directory:

```bash
workpeg cdn submit ./dist
```

Current directory:

```bash
workpeg cdn submit .
```

Custom CDN path:

```bash
workpeg cdn submit ./dist --path assets
```

Upload archive exactly without extraction:

```bash
workpeg cdn submit ./dist \
  --path archives/dist.tar.gz \
  --exact
```

Authentication uses:

```bash
export WORKPEG_PK=<your-token>
```

Default registry:

```text
https://repo.workpeg.com
```

---

# 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

Execution progression:

```text
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
workpeg function run --with docker
```

Runtime resolution order:

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

---

# Configuration

Optional project configuration:

```text
workpeg.json
```

Example:

```json
{
  "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
def main(context: dict, payload: dict):
    return {...}
```

Input:

```json
{
  "context": {...},
  "payload": {...}
}
```

Success output:

```json
{
  "status": "success",
  "result": {...}
}
```

Error output:

```json
{
  "status": "error",
  "error_type": "...",
  "error": "..."
}
```

---

# Entrypoint

Default entrypoint:

```text
app.main:main
```

Override:

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

---

# Docker Requirements

Required for:

```bash
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
-v /var/run/docker.sock:/var/run/docker.sock
```

---

# Philosophy

Workpeg is designed around portable executable applications.

Core progression:

```text
Function → Runtime → Peg → PegStore → Ecosystem
```

* Functions provide isolated runtime units
* Pegs package functionality into portable micro-apps
* PegStore enables discovery and distribution
* Workpeg provides runtime, packaging, and orchestration foundations

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
