Metadata-Version: 2.4
Name: workpeg
Version: 0.3.2
Summary: Workpeg function runtime and SDK
Author-email: Workpeg <support@workpeg.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/workpeg/workpeg
Project-URL: Repository, https://gitlab.com/workpeg/workpeg
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 for building, packaging, and running **Workpeg Functions and Pegs**.

The SDK provides:

* Project scaffolding
* Local execution (fast + Docker runtime)
* Docker-based packaging
* Registry submission

Workpeg is designed as an **execution layer**, not just a code runner — functions evolve into **Pegs** that integrate into a larger system.

**Repository**
[https://gitlab.com/workpeg/workpeg-sdk](https://gitlab.com/workpeg/workpeg-sdk)

---

# Installation

```bash
pip install workpeg
```

Or from source:

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

---

# Quick Start

## 1. Create a Function

```bash
workpeg new-function my-function
```

Structure:

```
my-function/
  app/
    __init__.py
    main.py
```

Example:

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

---

## 2. Run (Fast Local Runtime)

For quick iteration without Docker:

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

---

## 3. Build (Docker Image)

```bash
workpeg build
```

Optional tag:

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

This produces a runnable container for your function.

---

## 4. Run (Docker Runtime)

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

This will:

* Build the image (if needed)
* Start a container
* Expose an HTTP endpoint

Default:

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

### Optional network (advanced)

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

Useful when integrating with other containers (e.g. your API service).

---

## 5. Submit to Registry

```bash
workpeg submit my-function:1.0.0
```

Authentication:

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

Registry:

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

---

# Runtime Modes

Workpeg supports multiple execution backends:

| Runtime | Purpose              | Status      |
| ------- | -------------------- | ----------- |
| docker  | Local development    | ✅ Available |
| cracker | Firecracker microVMs | 🚧 Planned  |

Select runtime:

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

If unspecified:

1. Uses `workpeg.json`
2. Falls back to `cracker` (future default)

---

# Configuration

Optional config file:

```
workpeg.json
```

Example:

```json
{
  "runtime": {
    "default": "docker",
    "docker": {
      "port": 8000
    }
  },
  "build": {
    "image": "my-custom-image"
  }
}
```

---

# Function Contract

Your function must 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:

```
app.main:main
```

Override:

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

---

# Project Layout

```
my-function/
 ├─ app/
 │  ├─ __init__.py
 │  └─ main.py
 ├─ requirements.txt
 └─ workpeg.json (optional)
```

---

# Docker Requirement (Important)

For `workpeg build` and `workpeg run --with docker`:

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

If using inside containers:

```bash
-v /var/run/docker.sock:/var/run/docker.sock
```

---

# Philosophy

Workpeg is built around a simple progression:

```
Function → Package → Runtime → Peg → System
```

* Functions are stateless execution units
* Pegs add structure, state, and integrations
* Workpeg orchestrates execution

---

# Roadmap

Planned:

* Firecracker runtime (production)
* Warm container/microVM execution
* Peg UI layer (Streamlit-like)
* Deployment workflows
* Isolation + sandboxing
* Registry approvals & governance

---

# License

MIT License
