seekapi 1.0.0__tar.gz

seekapi-1.0.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: seekapi
+Version: 1.0.0
+Summary: SDK for SeekAPI workers: input/output handling, push data and files, success/failure.
+Author: SeekAPI
+License: MIT
+Project-URL: Repository, https://github.com/seekapi/workers
+Keywords: seekapi,worker,lambda,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SeekAPI Python SDK
+
+SDK for building SeekAPI workers in Python. Handles **input** (fetch from presigned URL) and **output** (push JSON and files), with a minimal Lambda return contract.
+
+- **Zero dependencies** — uses only the standard library.
+- **Python 3.10+** — works in AWS Lambda runtimes.
+
+## Install
+
+```bash
+pip install seekapi
+```
+
+## Quick start (recommended)
+
+Use `run()` so the SDK handles input, output, and errors. You only implement a function from input → output:
+
+```python
+from seekapi import run
+
+def handler(event, context):
+    return run(event, context, lambda input: {
+        "message": f"hello {input.get('name', 'world')}"
+    })
+```
+
+## Low-level API
+
+When you need more control (e.g. multiple `push_data` calls or `push_file`):
+
+```python
+from seekapi import (
+    get_input,
+    create_context,
+    push_data,
+    push_file,
+    register_request_id,
+    success,
+    failure,
+)
+
+def handler(event, context):
+    request_id = getattr(context, "aws_request_id", None) if context else None
+    job_uuid = (event.get("job_uuid") or "").strip()
+    if request_id and job_uuid:
+        register_request_id(job_uuid, request_id)
+
+    ctx = create_context(event)
+    try:
+        input_data = get_input(event)   # fetches and parses JSON from input_presigned_url
+        # ... your logic ...
+        push_data(ctx, {"result": "ok"})
+        return success(request_id=request_id)
+    except Exception as e:
+        return failure("WORKER_ERROR", str(e), request_id=request_id)
+```
+
+### API reference
+
+| Function | Description |
+|----------|-------------|
+| `get_input(event, timeout=10)` | Fetch and parse job input JSON from `event["input_presigned_url"]`. Raises `MissingInputError` if URL missing, `ValueError` on HTTP/JSON errors. |
+| `create_context(event)` | Build context dict for push_data/push_file (job_uuid, execution_token, api_base, secret from env). |
+| `push_data(context, data, type="json")` | Push JSON to the job (overwrites response_json). |
+| `push_file(context, name, local_path, content_type=None)` | Push a file to the job temp_files. |
+| `register_request_id(job_uuid, request_id)` | Register Lambda request_id for live logs (no-op if env not set). |
+| `success(request_id=None)` | Return `{ "ok": true, "request_id"? }`. |
+| `failure(code, message, request_id=None)` | Return `{ "ok": false, "error": { "code", "message" }, "request_id"? }`. |
+| `run(event, context, user_fn)` | Get input → call `user_fn(input)` → push result → return success; on exception return failure. |
+
+### Environment (set by the platform)
+
+- `WORKER_API_BASE_URL` — backend base URL for push and register_request_id.
+- `WORKER_INTERNAL_SECRET` — secret for internal API auth.
+
+### Errors
+
+- **MissingInputError** — `event` has no `input_presigned_url`.
+- **ValueError** — Input fetch failed (HTTP error, timeout, invalid JSON). Message is descriptive.
+
+## Publishing to PyPI
+
+From the package directory:
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Use a version bump and tag before each release.

seekapi-1.0.0/README.md

@@ -0,0 +1,91 @@
+# SeekAPI Python SDK
+
+SDK for building SeekAPI workers in Python. Handles **input** (fetch from presigned URL) and **output** (push JSON and files), with a minimal Lambda return contract.
+
+- **Zero dependencies** — uses only the standard library.
+- **Python 3.10+** — works in AWS Lambda runtimes.
+
+## Install
+
+```bash
+pip install seekapi
+```
+
+## Quick start (recommended)
+
+Use `run()` so the SDK handles input, output, and errors. You only implement a function from input → output:
+
+```python
+from seekapi import run
+
+def handler(event, context):
+    return run(event, context, lambda input: {
+        "message": f"hello {input.get('name', 'world')}"
+    })
+```
+
+## Low-level API
+
+When you need more control (e.g. multiple `push_data` calls or `push_file`):
+
+```python
+from seekapi import (
+    get_input,
+    create_context,
+    push_data,
+    push_file,
+    register_request_id,
+    success,
+    failure,
+)
+
+def handler(event, context):
+    request_id = getattr(context, "aws_request_id", None) if context else None
+    job_uuid = (event.get("job_uuid") or "").strip()
+    if request_id and job_uuid:
+        register_request_id(job_uuid, request_id)
+
+    ctx = create_context(event)
+    try:
+        input_data = get_input(event)   # fetches and parses JSON from input_presigned_url
+        # ... your logic ...
+        push_data(ctx, {"result": "ok"})
+        return success(request_id=request_id)
+    except Exception as e:
+        return failure("WORKER_ERROR", str(e), request_id=request_id)
+```
+
+### API reference
+
+| Function | Description |
+|----------|-------------|
+| `get_input(event, timeout=10)` | Fetch and parse job input JSON from `event["input_presigned_url"]`. Raises `MissingInputError` if URL missing, `ValueError` on HTTP/JSON errors. |
+| `create_context(event)` | Build context dict for push_data/push_file (job_uuid, execution_token, api_base, secret from env). |
+| `push_data(context, data, type="json")` | Push JSON to the job (overwrites response_json). |
+| `push_file(context, name, local_path, content_type=None)` | Push a file to the job temp_files. |
+| `register_request_id(job_uuid, request_id)` | Register Lambda request_id for live logs (no-op if env not set). |
+| `success(request_id=None)` | Return `{ "ok": true, "request_id"? }`. |
+| `failure(code, message, request_id=None)` | Return `{ "ok": false, "error": { "code", "message" }, "request_id"? }`. |
+| `run(event, context, user_fn)` | Get input → call `user_fn(input)` → push result → return success; on exception return failure. |
+
+### Environment (set by the platform)
+
+- `WORKER_API_BASE_URL` — backend base URL for push and register_request_id.
+- `WORKER_INTERNAL_SECRET` — secret for internal API auth.
+
+### Errors
+
+- **MissingInputError** — `event` has no `input_presigned_url`.
+- **ValueError** — Input fetch failed (HTTP error, timeout, invalid JSON). Message is descriptive.
+
+## Publishing to PyPI
+
+From the package directory:
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Use a version bump and tag before each release.

seekapi-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "seekapi"
+version = "1.0.0"
+description = "SDK for SeekAPI workers: input/output handling, push data and files, success/failure."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "SeekAPI" }]
+keywords = ["seekapi", "worker", "lambda", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Repository = "https://github.com/seekapi/workers"
+
+[tool.setuptools.packages.find]
+where = ["src"]

seekapi-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

seekapi-1.0.0/src/seekapi/__init__.py

@@ -0,0 +1,218 @@
+"""SeekAPI worker SDK: get_input, push_data/push_file, run(), success/failure.
+Zero dependencies; use in AWS Lambda workers with WORKER_API_BASE_URL and WORKER_INTERNAL_SECRET set."""
+
+import json
+import mimetypes
+import os
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+
+class MissingInputError(ValueError):
+    """Raised when event has no input_presigned_url."""
+
+
+def get_input(event: dict, timeout: int = 10) -> dict:
+    """Fetch and parse job input from the presigned URL in the event.
+    Returns the JSON body as a dict. Raises MissingInputError if input_presigned_url
+    is missing, or ValueError on HTTP/JSON errors (with a clear message)."""
+    url = (event.get("input_presigned_url") or "").strip()
+    if not url:
+        raise MissingInputError("Missing input_presigned_url in event")
+    try:
+        with urlopen(url, timeout=timeout) as resp:
+            if resp.status >= 400:
+                raise ValueError(f"Input URL returned HTTP {resp.status}")
+            body = resp.read().decode("utf-8")
+        return json.loads(body)
+    except (HTTPError, URLError) as e:
+        raise ValueError(f"Failed to fetch input: {e}") from e
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid JSON in input: {e}") from e
+
+
+def create_context(event: dict) -> dict:
+    """Build context from Lambda event for push_data/push_file.
+    Returns dict with job_uuid, execution_token, api_base, secret (from env)."""
+    job_uuid = (event.get("job_uuid") or "").strip()
+    execution_token = (event.get("execution_token") or "").strip()
+    api_base = (os.environ.get("WORKER_API_BASE_URL") or "").strip().rstrip("/")
+    secret = (os.environ.get("WORKER_INTERNAL_SECRET") or "").strip()
+    return {
+        "job_uuid": job_uuid,
+        "execution_token": execution_token,
+        "api_base": api_base,
+        "secret": secret,
+    }
+
+
+def register_request_id(job_uuid: str, request_id: str) -> None:
+    """Call the API to register this Lambda's request_id so live execution logs can be streamed.
+    No-op if WORKER_API_BASE_URL or WORKER_INTERNAL_SECRET is not set."""
+    base = (os.environ.get("WORKER_API_BASE_URL") or "").strip().rstrip("/")
+    secret = (os.environ.get("WORKER_INTERNAL_SECRET") or "").strip()
+    if not base or not secret:
+        return
+    url = f"{base}/v1/internal/jobs/{job_uuid}/worker-request-id"
+    try:
+        data = json.dumps({"request_id": request_id}).encode("utf-8")
+        req = Request(
+            url,
+            data=data,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "X-Internal-Secret": secret,
+            },
+        )
+        urlopen(req, timeout=5)
+    except (HTTPError, URLError, OSError):
+        pass
+
+
+def push_data(
+    context: dict,
+    data: dict,
+    type: str = "json",
+) -> None:
+    """Push JSON data to the job (overwrites response_json). No-op if api_base/secret not set."""
+    api_base = context.get("api_base") or ""
+    secret = context.get("secret") or ""
+    job_uuid = context.get("job_uuid") or ""
+    execution_token = context.get("execution_token") or ""
+    if not api_base or not secret or not job_uuid or not execution_token:
+        return
+    url = f"{api_base}/v1/internal/jobs/{job_uuid}/push"
+    try:
+        body = json.dumps({
+            "execution_token": execution_token,
+            "data": data,
+            "type": type,
+        }).encode("utf-8")
+        req = Request(
+            url,
+            data=body,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "X-Internal-Secret": secret,
+            },
+        )
+        urlopen(req, timeout=30)
+    except (HTTPError, URLError, OSError):
+        raise
+
+
+def push_file(
+    context: dict,
+    name: str,
+    local_path: str,
+    content_type: str | None = None,
+) -> None:
+    """Push a file from local_path to the job temp_files. No-op if api_base/secret not set."""
+    api_base = context.get("api_base") or ""
+    secret = context.get("secret") or ""
+    job_uuid = context.get("job_uuid") or ""
+    execution_token = context.get("execution_token") or ""
+    if not api_base or not secret or not job_uuid or not execution_token:
+        return
+    url = f"{api_base}/v1/internal/jobs/{job_uuid}/push/file"
+    ct = content_type
+    if not ct:
+        ct, _ = mimetypes.guess_type(local_path)
+        ct = ct or "application/octet-stream"
+    try:
+        with open(local_path, "rb") as f:
+            body_bytes = f.read()
+    except OSError:
+        raise
+
+    # multipart/form-data: execution_token, name, file
+    boundary = "----WorkerSDKBoundary" + os.urandom(8).hex()
+    b = boundary.encode("ascii")
+    crlf = b"\r\n"
+    body_parts = [
+        b"--" + b + crlf,
+        b'Content-Disposition: form-data; name="execution_token"' + crlf + crlf,
+        execution_token.encode("utf-8"),
+        crlf,
+        b"--" + b + crlf,
+        b'Content-Disposition: form-data; name="name"' + crlf + crlf,
+        name.encode("utf-8"),
+        crlf,
+        b"--" + b + crlf,
+        b'Content-Disposition: form-data; name="file"; filename="' + name.encode("utf-8") + b'"' + crlf,
+        b"Content-Type: " + ct.encode("ascii") + crlf + crlf,
+        body_bytes,
+        crlf,
+        b"--" + b + b"--" + crlf,
+    ]
+    body = b"".join(body_parts)
+    req = Request(
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "Content-Type": f"multipart/form-data; boundary={boundary}",
+            "X-Internal-Secret": secret,
+        },
+    )
+    try:
+        urlopen(req, timeout=60)
+    except (HTTPError, URLError, OSError):
+        raise
+
+
+def success(request_id: str | None = None) -> dict:
+    """Return minimal success payload for Lambda. Result is taken from last push_data."""
+    out: dict = {"ok": True}
+    if request_id:
+        out["request_id"] = request_id
+    return out
+
+
+def failure(code: str, message: str, request_id: str | None = None) -> dict:
+    """Return minimal failure payload for Lambda."""
+    out: dict = {
+        "ok": False,
+        "error": {"code": code, "message": message},
+    }
+    if request_id:
+        out["request_id"] = request_id
+    return out
+
+
+def run(
+    event: dict,
+    context: object,
+    user_fn: "object",  # Callable[[dict], dict]
+) -> dict:
+    """Run a worker with input/output handled by the SDK.
+    Fetches input via get_input(event), calls user_fn(input_data), pushes the
+    result via push_data, and returns success(request_id). On any exception,
+    returns failure('WORKER_ERROR', str(e), request_id)."""
+    request_id = getattr(context, "aws_request_id", None) if context else None
+    job_uuid = (event.get("job_uuid") or "").strip()
+    if request_id and job_uuid:
+        register_request_id(job_uuid, request_id)
+    ctx = create_context(event)
+    try:
+        input_data = get_input(event)
+        result = user_fn(input_data)
+        push_data(ctx, result)
+        return success(request_id=request_id)
+    except Exception as e:
+        return failure("WORKER_ERROR", str(e), request_id=request_id)
+
+
+__all__ = [
+    "MissingInputError",
+    "get_input",
+    "create_context",
+    "register_request_id",
+    "push_data",
+    "push_file",
+    "success",
+    "failure",
+    "run",
+]

seekapi-1.0.0/src/seekapi.egg-info/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: seekapi
+Version: 1.0.0
+Summary: SDK for SeekAPI workers: input/output handling, push data and files, success/failure.
+Author: SeekAPI
+License: MIT
+Project-URL: Repository, https://github.com/seekapi/workers
+Keywords: seekapi,worker,lambda,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SeekAPI Python SDK
+
+SDK for building SeekAPI workers in Python. Handles **input** (fetch from presigned URL) and **output** (push JSON and files), with a minimal Lambda return contract.
+
+- **Zero dependencies** — uses only the standard library.
+- **Python 3.10+** — works in AWS Lambda runtimes.
+
+## Install
+
+```bash
+pip install seekapi
+```
+
+## Quick start (recommended)
+
+Use `run()` so the SDK handles input, output, and errors. You only implement a function from input → output:
+
+```python
+from seekapi import run
+
+def handler(event, context):
+    return run(event, context, lambda input: {
+        "message": f"hello {input.get('name', 'world')}"
+    })
+```
+
+## Low-level API
+
+When you need more control (e.g. multiple `push_data` calls or `push_file`):
+
+```python
+from seekapi import (
+    get_input,
+    create_context,
+    push_data,
+    push_file,
+    register_request_id,
+    success,
+    failure,
+)
+
+def handler(event, context):
+    request_id = getattr(context, "aws_request_id", None) if context else None
+    job_uuid = (event.get("job_uuid") or "").strip()
+    if request_id and job_uuid:
+        register_request_id(job_uuid, request_id)
+
+    ctx = create_context(event)
+    try:
+        input_data = get_input(event)   # fetches and parses JSON from input_presigned_url
+        # ... your logic ...
+        push_data(ctx, {"result": "ok"})
+        return success(request_id=request_id)
+    except Exception as e:
+        return failure("WORKER_ERROR", str(e), request_id=request_id)
+```
+
+### API reference
+
+| Function | Description |
+|----------|-------------|
+| `get_input(event, timeout=10)` | Fetch and parse job input JSON from `event["input_presigned_url"]`. Raises `MissingInputError` if URL missing, `ValueError` on HTTP/JSON errors. |
+| `create_context(event)` | Build context dict for push_data/push_file (job_uuid, execution_token, api_base, secret from env). |
+| `push_data(context, data, type="json")` | Push JSON to the job (overwrites response_json). |
+| `push_file(context, name, local_path, content_type=None)` | Push a file to the job temp_files. |
+| `register_request_id(job_uuid, request_id)` | Register Lambda request_id for live logs (no-op if env not set). |
+| `success(request_id=None)` | Return `{ "ok": true, "request_id"? }`. |
+| `failure(code, message, request_id=None)` | Return `{ "ok": false, "error": { "code", "message" }, "request_id"? }`. |
+| `run(event, context, user_fn)` | Get input → call `user_fn(input)` → push result → return success; on exception return failure. |
+
+### Environment (set by the platform)
+
+- `WORKER_API_BASE_URL` — backend base URL for push and register_request_id.
+- `WORKER_INTERNAL_SECRET` — secret for internal API auth.
+
+### Errors
+
+- **MissingInputError** — `event` has no `input_presigned_url`.
+- **ValueError** — Input fetch failed (HTTP error, timeout, invalid JSON). Message is descriptive.
+
+## Publishing to PyPI
+
+From the package directory:
+
+```bash
+pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Use a version bump and tag before each release.

seekapi-1.0.0/src/seekapi.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+README.md
+pyproject.toml
+src/seekapi/__init__.py
+src/seekapi.egg-info/PKG-INFO
+src/seekapi.egg-info/SOURCES.txt
+src/seekapi.egg-info/dependency_links.txt
+src/seekapi.egg-info/top_level.txt

seekapi-1.0.0/src/seekapi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

seekapi-1.0.0/src/seekapi.egg-info/top_level.txt

@@ -0,0 +1 @@
+seekapi