workpeg 0.5.0__tar.gz → 0.5.2__tar.gz

workpeg-0.5.2/PKG-INFO

@@ -0,0 +1,438 @@
+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