Metadata-Version: 2.4
Name: workpeg
Version: 0.6.1
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, packaging, publishing, and distributing Workpeg Pegs.

Workpeg is a platform for developing portable applications called Pegs. Pegs can be built, packaged, distributed through the PegStore, and integrated into the broader Workpeg ecosystem.

The SDK currently focuses on function-based Peg development, runtime tooling, Docker packaging, registry publishing, and CDN asset management. The CLI is namespace-oriented and designed to grow alongside the platform.

---

# 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 such as Docker.

Current namespaces:

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

| Namespace | Purpose                                          |
| --------- | ------------------------------------------------ |
| function  | Create, build, run and publish Workpeg Functions |
| cdn       | Upload public Peg assets                         |

Future namespaces may include:

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

Get help:

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

---

# Quick Start

## Create a Function

Create a new function project:

```bash
workpeg function new hello
```

Generated structure:

```text
hello/
├── app/
│   ├── __init__.py
│   └── main.py
├── 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 quick 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 a warm HTTP runtime:

```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 a Function

Build a Docker image:

```bash
workpeg function build
```

Custom image tag:

```bash
workpeg function build --tag my-image
```

The build process creates a portable runtime image for the Function.

---

# Run a Function

Run using Docker:

```bash
workpeg function run --with docker
```

This will:

* Build the image (unless disabled)
* Start a detached runtime container
* Enable warm execution
* Expose HTTP endpoints

Default endpoint:

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

---

# Docker Networking

Attach a runtime to a Docker network:

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

Assign a container name:

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

Other containers can then reach the runtime via:

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

This allows multiple Pegs to run simultaneously without host port collisions.

---

# Publish a Function

Submit a Function version to the Workpeg Registry:

```bash
workpeg function submit hello:1.0.0
```

Authentication:

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

Default registry:

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

---

# CDN Asset Uploads

Upload public Peg assets to the CDN.

Single file:

```bash
workpeg cdn submit logo.svg
```

Directory:

```bash
workpeg cdn submit ./assets
```

Current directory:

```bash
workpeg cdn submit .
```

Specify a target CDN path:

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

Replace existing assets:

```bash
workpeg cdn submit ./assets --overwrite
```

Upload an archive exactly without extraction:

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

Authentication uses:

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

The CDN uses the same authentication token as the Registry.

---

# Recommended Peg Asset Structure

```text
assets/
├── logo/
│   ├── icon.svg
│   ├── icon.png
│   ├── light.svg
│   └── dark.svg
│
├── screenshots/
│   ├── 01-dashboard.png
│   ├── 02-mobile.png
│   └── 03-settings.png
│
├── banners/
│   ├── hero.png
│   └── cover.png
│
├── social/
│   └── og.png
│
└── metadata/
    └── manifest.json
```

Publish assets:

```bash
workpeg cdn submit ./assets --overwrite
```

---

# Runtime Backends

Workpeg supports multiple runtime backends.

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

Select runtime:

```bash
workpeg function run --with docker
```

Resolution order:

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

---

# Configuration

Optional project configuration:

```text
workpeg.json
```

Example:

```json
{
  "name": "hello",
  "description": "Example Workpeg Function",

  "runtime": {
    "default": "docker",
    "docker": {
      "port": 8000
    }
  },

  "build": {
    "image": "workpeg-fn-hello"
  },

  "function": {
    "entrypoint": "app.main:main"
  },

  "cdn": {
    "assets_path": "assets"
  }
}
```

---

# 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:

```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
```

---

# Development Lifecycle

Typical development flow:

```bash
workpeg function new hello

workpeg function build

workpeg function run --with docker

workpeg function submit hello:1.0.0

workpeg cdn submit ./assets --overwrite
```

Progression:

```text
Developer
    ↓
Function
    ↓
Package
    ↓
Peg
    ↓
PegStore
```

---

# Philosophy

Workpeg is designed around portable applications.

Core progression:

```text
Developer → Function → Peg → PegStore → Ecosystem
```

* Functions provide reusable application logic
* Pegs package functionality into portable micro-apps
* PegStore enables discovery and distribution
* Workpeg provides the tooling required to build and publish them

The long-term goal is a platform where developers can create, distribute, and monetize applications through a unified ecosystem.

---

# Roadmap

Planned:

* Firecracker runtime backend
* Persistent microVM execution
* Peg packaging workflows
* PegStore publishing tools
* Client application tooling
* Runtime orchestration
* Registry governance & approvals
* Distributed runtime scheduling
* Additional CLI namespaces

---

# License

MIT License
