runit-sdk 0.1.0__tar.gz

runit_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: runit-sdk
+Version: 0.1.0
+Summary: SDK for building apps on RunIt
+Home-page: https://github.com/buildingopen/runit
+Author: RunIt
+Author-email: RunIt <hello@buildingopen.org>
+License: MIT
+Project-URL: Documentation, https://docs.runit.dev
+Project-URL: Source, https://github.com/buildingopen/runit
+Project-URL: Tracker, https://github.com/buildingopen/runit/issues
+Keywords: fastapi,runit,sdk,api,deployment
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dataframe
+Requires-Dist: pandas>=2.0.0; extra == "dataframe"
+Requires-Dist: pyarrow>=14.0.0; extra == "dataframe"
+Provides-Extra: excel
+Requires-Dist: pandas>=2.0.0; extra == "excel"
+Requires-Dist: openpyxl>=3.1.0; extra == "excel"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pandas>=2.0.0; extra == "dev"
+Requires-Dist: pyarrow>=14.0.0; extra == "dev"
+Requires-Dist: openpyxl>=3.1.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# RunIt SDK
+
+Simple utilities for building FastAPI apps on RunIt.
+
+## Installation
+
+The SDK is automatically available in the RunIt runtime. For local development:
+
+```bash
+pip install -e .
+```
+
+Or install from PyPI (when published):
+
+```bash
+pip install runit
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from runit import context, save_artifact
+
+app = FastAPI()
+
+@app.post("/process")
+async def process(data: dict):
+    # Access secrets
+    api_key = context.get_secret("OPENAI_API_KEY")
+
+    # Access uploaded context
+    company = context.get_context("company")
+
+    # Save results
+    save_artifact("output.json", json.dumps(result))
+
+    return {"status": "success"}
+```
+
+## Features
+
+- **Context Access** - Read secrets and uploaded JSON data
+- **Artifact Saving** - Write outputs that users can download
+- **DataFrame Export** - Save pandas/polars DataFrames in multiple formats
+- **Zero Dependencies** - Core functionality has no required dependencies
+
+## Documentation
+
+See the [SDK Guide](../../../docs/SDK_GUIDE.md) for complete documentation and examples.
+
+## Sample Apps
+
+Check out the sample apps in `../samples/`:
+
+- `extract-company` - URL scraping with artifacts
+- `image-analysis` - File upload and image processing
+- `bulk-processor` - Batch processing with error handling
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=runit --cov-report=html
+```
+
+## License
+
+MIT

runit_sdk-0.1.0/README.md

@@ -0,0 +1,75 @@
+# RunIt SDK
+
+Simple utilities for building FastAPI apps on RunIt.
+
+## Installation
+
+The SDK is automatically available in the RunIt runtime. For local development:
+
+```bash
+pip install -e .
+```
+
+Or install from PyPI (when published):
+
+```bash
+pip install runit
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from runit import context, save_artifact
+
+app = FastAPI()
+
+@app.post("/process")
+async def process(data: dict):
+    # Access secrets
+    api_key = context.get_secret("OPENAI_API_KEY")
+
+    # Access uploaded context
+    company = context.get_context("company")
+
+    # Save results
+    save_artifact("output.json", json.dumps(result))
+
+    return {"status": "success"}
+```
+
+## Features
+
+- **Context Access** - Read secrets and uploaded JSON data
+- **Artifact Saving** - Write outputs that users can download
+- **DataFrame Export** - Save pandas/polars DataFrames in multiple formats
+- **Zero Dependencies** - Core functionality has no required dependencies
+
+## Documentation
+
+See the [SDK Guide](../../../docs/SDK_GUIDE.md) for complete documentation and examples.
+
+## Sample Apps
+
+Check out the sample apps in `../samples/`:
+
+- `extract-company` - URL scraping with artifacts
+- `image-analysis` - File upload and image processing
+- `bulk-processor` - Batch processing with error handling
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=runit --cov-report=html
+```
+
+## License
+
+MIT

runit_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runit-sdk"
+version = "0.1.0"
+description = "SDK for building apps on RunIt"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [
+    {name = "RunIt", email = "hello@buildingopen.org"}
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+keywords = ["fastapi", "runit", "sdk", "api", "deployment"]
+
+[project.optional-dependencies]
+dataframe = [
+    "pandas>=2.0.0",
+    "pyarrow>=14.0.0",
+]
+excel = [
+    "pandas>=2.0.0",
+    "openpyxl>=3.1.0",
+]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1.0",
+    "pandas>=2.0.0",
+    "pyarrow>=14.0.0",
+    "openpyxl>=3.1.0",
+]
+
+[project.urls]
+Documentation = "https://docs.runit.dev"
+Source = "https://github.com/buildingopen/runit"
+Tracker = "https://github.com/buildingopen/runit/issues"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --strict-markers"
+
+[tool.coverage.run]
+source = ["runit"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+fail_under = 77
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]

runit_sdk-0.1.0/runit/__init__.py

@@ -0,0 +1,21 @@
+# ABOUTME: RunIt Python SDK. Exposes app, storage, remember, artifacts, and context.
+# ABOUTME: Usage: from runit import app, remember; @app.action; remember("key", value)
+
+from runit._app import App, app
+from runit._storage import forget, remember, storage
+from runit.artifacts import save_artifact, save_dataframe, save_json
+from runit.context import Context, context
+
+__version__ = "0.1.0"
+__all__ = [
+    "app",
+    "App",
+    "storage",
+    "remember",
+    "forget",
+    "save_artifact",
+    "save_dataframe",
+    "save_json",
+    "context",
+    "Context",
+]

runit_sdk-0.1.0/runit/_app.py

@@ -0,0 +1,55 @@
+# ABOUTME: RunIt app class with @app.action decorator for marking functions as RunIt actions.
+# ABOUTME: Syntactic sugar that makes intent explicit.
+# ABOUTME: Runner checks _runit_action attribute on functions.
+
+
+class App:
+    """RunIt application container.
+
+    Use @app.action to mark functions as RunIt actions.
+    The runner uses this to discover which functions to expose.
+
+    Example:
+        from runit import app
+
+        @app.action
+        def greet(name: str) -> dict:
+            return {"message": f"Hello, {name}!"}
+
+        @app.action(name="custom_name")
+        def my_func(x: int) -> dict:
+            return {"result": x * 2}
+    """
+
+    def __init__(self):
+        self._actions = []
+
+    def action(self, func=None, *, name=None):
+        """Mark a function as a RunIt action.
+
+        Can be used with or without arguments:
+            @app.action
+            def my_func(): ...
+
+            @app.action(name="custom")
+            def my_func(): ...
+        """
+
+        def decorator(f):
+            f._runit_action = True
+            f._runit_name = name or f.__name__
+            self._actions.append(f)
+            return f
+
+        if func is not None:
+            return decorator(func)
+        return decorator
+
+    @property
+    def actions(self):
+        """List of registered action functions."""
+        return list(self._actions)
+
+
+# Singleton instance
+app = App()

runit_sdk-0.1.0/runit/_storage.py

@@ -0,0 +1,216 @@
+# ABOUTME: StorageClient for persistent key-value storage inside runner containers.
+# ABOUTME: Reads/writes files at RUNIT_STORAGE_DIR (/storage).
+# ABOUTME: Atomic writes via rename. 10MB/value, 100MB/project.
+
+import json
+import os
+import re
+import tempfile
+
+KEY_PATTERN = re.compile(r"^[a-zA-Z0-9._-]+$")
+MAX_KEY_LENGTH = 256
+MAX_VALUE_SIZE = 10 * 1024 * 1024  # 10MB per value
+DEFAULT_MAX_PROJECT_SIZE = 100 * 1024 * 1024  # 100MB per project
+USAGE_FILE = ".usage"
+
+
+class StorageClient:
+    """Persistent key-value storage for RunIt projects.
+
+    Values are stored as files in the storage directory, mounted by the runner.
+    Supports JSON-serializable values and raw strings.
+    """
+
+    def __init__(self):
+        self._dir = os.environ.get("RUNIT_STORAGE_DIR", "/storage")
+        self._max_project_size = int(
+            os.environ.get("RUNIT_STORAGE_MAX_PROJECT_SIZE", str(DEFAULT_MAX_PROJECT_SIZE))
+        )
+
+    def _validate_key(self, key):
+        if not key or len(key) == 0:
+            raise ValueError("Key is required")
+        if len(key) > MAX_KEY_LENGTH:
+            raise ValueError(f"Key exceeds maximum length of {MAX_KEY_LENGTH} characters")
+        if not KEY_PATTERN.match(key):
+            raise ValueError(
+                "Key must contain only alphanumeric characters, dots, underscores, and hyphens"
+            )
+        if ".." in key or key.startswith(".") or key.endswith("."):
+            raise ValueError("Key must not start/end with dots or contain consecutive dots")
+
+    def _path(self, key):
+        path = os.path.join(self._dir, key)
+        real = os.path.realpath(path)
+        storage_dir = os.path.realpath(self._dir)
+        if not real.startswith(storage_dir + os.sep) and real != storage_dir:
+            raise ValueError("Storage key resolves outside storage directory")
+        return path
+
+    def _ensure_dir(self):
+        os.makedirs(self._dir, exist_ok=True)
+
+    def _compute_usage(self):
+        """Calculate total storage usage by scanning files."""
+        total = 0
+        if not os.path.isdir(self._dir):
+            return 0
+        for name in os.listdir(self._dir):
+            if name == USAGE_FILE or name.endswith(".tmp"):
+                continue
+            fpath = os.path.join(self._dir, name)
+            if os.path.isfile(fpath):
+                total += os.path.getsize(fpath)
+        return total
+
+    def _update_usage(self):
+        """Write current usage to .usage file."""
+        usage = self._compute_usage()
+        usage_path = os.path.join(self._dir, USAGE_FILE)
+        with open(usage_path, "w") as f:
+            f.write(str(usage))
+        return usage
+
+    def set(self, key, value):
+        """Store a value. Accepts any JSON-serializable object or string.
+
+        Args:
+            key: Storage key (alphanumeric, dots, underscores, hyphens; max 256 chars)
+            value: Value to store (JSON-serialized automatically)
+
+        Raises:
+            ValueError: If key is invalid or value exceeds size limits
+        """
+        self._validate_key(key)
+        self._ensure_dir()
+
+        serialized = json.dumps(value)
+        size = len(serialized.encode("utf-8"))
+
+        if size > MAX_VALUE_SIZE:
+            raise ValueError(f"Value size ({size} bytes) exceeds maximum of {MAX_VALUE_SIZE} bytes")
+
+        # Check quota
+        existing_size = 0
+        existing_path = self._path(key)
+        if os.path.isfile(existing_path):
+            existing_size = os.path.getsize(existing_path)
+
+        current_usage = self._compute_usage()
+        projected = current_usage - existing_size + size
+        if projected > self._max_project_size:
+            raise ValueError(
+                f"Project storage quota exceeded ({projected} / {self._max_project_size} bytes)"
+            )
+
+        # Atomic write: write to temp, then rename
+        fd, tmp_path = tempfile.mkstemp(dir=self._dir, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w") as f:
+                f.write(serialized)
+            os.rename(tmp_path, existing_path)
+        except Exception:
+            # Clean up temp file on failure
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+            raise
+
+        self._update_usage()
+
+    def get(self, key, default=None):
+        """Retrieve a value by key.
+
+        Args:
+            key: Storage key
+            default: Value to return if key doesn't exist (default: None)
+
+        Returns:
+            The stored value (deserialized from JSON), or default if not found
+        """
+        self._validate_key(key)
+        path = self._path(key)
+        if not os.path.isfile(path):
+            return default
+
+        with open(path, "r") as f:
+            raw = f.read()
+        return json.loads(raw)
+
+    def delete(self, key):
+        """Delete a value by key.
+
+        Args:
+            key: Storage key
+
+        Returns:
+            True if the key existed and was deleted, False if not found
+        """
+        self._validate_key(key)
+        path = self._path(key)
+        if not os.path.isfile(path):
+            return False
+        os.unlink(path)
+        self._update_usage()
+        return True
+
+    def exists(self, key):
+        """Check if a key exists.
+
+        Args:
+            key: Storage key
+
+        Returns:
+            True if the key exists
+        """
+        self._validate_key(key)
+        return os.path.isfile(self._path(key))
+
+    def list(self):
+        """List all storage keys.
+
+        Returns:
+            List of key names (strings)
+        """
+        if not os.path.isdir(self._dir):
+            return []
+        keys = []
+        for name in sorted(os.listdir(self._dir)):
+            if name == USAGE_FILE or name.endswith(".tmp"):
+                continue
+            fpath = os.path.join(self._dir, name)
+            if os.path.isfile(fpath):
+                keys.append(name)
+        return keys
+
+
+# Singleton instance
+storage = StorageClient()
+
+
+# ---- Human-friendly aliases ----
+
+_SENTINEL = object()
+
+
+def remember(key, value=_SENTINEL):
+    """If one arg: recall a stored value. If two args: store a value.
+
+    Examples:
+        remember("username", "Alice")   # stores "Alice"
+        remember("username")            # returns "Alice"
+    """
+    if value is _SENTINEL:
+        return storage.get(key)
+    storage.set(key, value)
+    return value
+
+
+def forget(key):
+    """Delete a stored value.
+
+    Example:
+        forget("username")  # removes "username" from storage
+    """
+    storage.delete(key)

runit_sdk-0.1.0/runit/artifacts.py

@@ -0,0 +1,146 @@
+"""
+Artifact writing utilities for RunIt.
+
+Provides helpers to save outputs that users can download:
+- save_artifact(): Save any file (text, binary, JSON)
+- save_dataframe(): Save pandas/polars DataFrames in various formats
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Literal
+
+# Get artifacts directory from environment
+ARTIFACTS_DIR = Path(os.getenv("EL_ARTIFACTS_DIR", "/artifacts"))
+
+
+def save_artifact(filename: str, data: bytes | str) -> str:
+    """
+    Save artifact and return path.
+
+    Artifacts are collected from /artifacts/ and made available for download.
+
+    Args:
+        filename: Name of the file to save
+        data: File content (string or bytes)
+
+    Returns:
+        Absolute path to saved file
+
+    Examples:
+        >>> from runit import save_artifact
+        >>>
+        >>> # Save text file
+        >>> save_artifact("output.txt", "Hello World")
+        >>>
+        >>> # Save JSON
+        >>> import json
+        >>> save_artifact("data.json", json.dumps({"key": "value"}))
+        >>>
+        >>> # Save binary data
+        >>> save_artifact("image.png", image_bytes)
+    """
+    # Ensure artifacts directory exists
+    ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Build full path
+    path = ARTIFACTS_DIR / filename
+
+    # Write data
+    if isinstance(data, str):
+        path.write_text(data, encoding="utf-8")
+    else:
+        path.write_bytes(data)
+
+    return str(path)
+
+
+def save_dataframe(
+    df: Any, filename: str, format: Literal["csv", "json", "parquet", "excel"] = "csv"
+) -> str:
+    """
+    Save pandas or polars DataFrame as artifact.
+
+    Args:
+        df: DataFrame to save (pandas or polars)
+        filename: Name of the file to save
+        format: Output format - "csv", "json", "parquet", or "excel"
+
+    Returns:
+        Absolute path to saved file
+
+    Examples:
+        >>> import pandas as pd
+        >>> from runit import save_dataframe
+        >>>
+        >>> df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+        >>>
+        >>> # Save as CSV
+        >>> save_dataframe(df, "output.csv")
+        >>>
+        >>> # Save as JSON
+        >>> save_dataframe(df, "output.json", format="json")
+        >>>
+        >>> # Save as Parquet
+        >>> save_dataframe(df, "output.parquet", format="parquet")
+    """
+    # Ensure artifacts directory exists
+    ARTIFACTS_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Build full path
+    path = ARTIFACTS_DIR / filename
+
+    # Try to detect DataFrame type and save accordingly
+    df_type = type(df).__name__
+
+    if format == "csv":
+        if hasattr(df, "to_csv"):
+            df.to_csv(path, index=False)
+        else:
+            raise TypeError(f"DataFrame type {df_type} does not support CSV export")
+
+    elif format == "json":
+        if hasattr(df, "to_json"):
+            df.to_json(path, orient="records", indent=2)
+        else:
+            raise TypeError(f"DataFrame type {df_type} does not support JSON export")
+
+    elif format == "parquet":
+        if hasattr(df, "to_parquet"):
+            df.to_parquet(path)
+        else:
+            raise TypeError(f"DataFrame type {df_type} does not support Parquet export")
+
+    elif format == "excel":
+        if hasattr(df, "to_excel"):
+            df.to_excel(path, index=False)
+        else:
+            raise TypeError(f"DataFrame type {df_type} does not support Excel export")
+
+    else:
+        raise ValueError(f"Unsupported format: {format}")
+
+    return str(path)
+
+
+def save_json(filename: str, data: Any) -> str:
+    """
+    Save data as JSON artifact.
+
+    Convenience wrapper around save_artifact() for JSON data.
+
+    Args:
+        filename: Name of the file to save
+        data: Any JSON-serializable data
+
+    Returns:
+        Absolute path to saved file
+
+    Examples:
+        >>> from runit import save_json
+        >>>
+        >>> save_json("result.json", {"status": "success", "count": 42})
+    """
+    json_str = json.dumps(data, indent=2, ensure_ascii=False)
+    return save_artifact(filename, json_str)