curupira-sdk 0.1.0.dev0__tar.gz

curupira_sdk-0.1.0.dev0/.gitignore

@@ -0,0 +1,190 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Local curupira configuration and runtime state
+/*-dispatch.toml
+*.sqlite3
+*.sqlite3-journal
+workspaces/
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# Pyrefly stuff:
+.pyrefly/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

curupira_sdk-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.5
+Name: curupira-sdk
+Version: 0.1.0.dev0
+Summary: Declarative SDK for Curupira JSON-RPC process extensions
+Requires-Python: >=3.11
+Provides-Extra: pydantic
+Requires-Dist: pydantic<3,>=2; extra == 'pydantic'

curupira_sdk-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "curupira-sdk"
+dynamic = ["version"]
+description = "Declarative SDK for Curupira JSON-RPC process extensions"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+pydantic = ["pydantic>=2,<3"]
+
+[build-system]
+requires = ["hatchling>=1.32.4,<2", "hatch-vcs>=0.5,<1"]
+build-backend = "hatchling.build"
+
+# The version is the publish/curupira-sdk/<version> git tag. Untagged builds get a
+# development version derived from the nearest tag of this package only.
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../..", tag_regex = "^publish/curupira-sdk/(?P<version>.+)$", git_describe_command = "git describe --tags --long --match publish/curupira-sdk/*", fallback_version = "0.1.0.dev0" }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/curupira_sdk"]

curupira_sdk-0.1.0.dev0/src/curupira_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""Declarative SDK for Curupira process extensions."""
+
+from __future__ import annotations
+
+from .app import Curupira
+from .errors import RegistrationError, RpcError, SerializationError, ValidationError
+from .framing import read_frame, write_frame
+from .server import ExtensionServer, serve_stdio
+
+__all__ = [
+    "Curupira",
+    "ExtensionServer",
+    "RegistrationError",
+    "RpcError",
+    "SerializationError",
+    "ValidationError",
+    "read_frame",
+    "serve_stdio",
+    "write_frame",
+]
+
+from importlib.metadata import version
+
+# Read from the installed distribution, whose version comes from the release tag.
+__version__ = version("curupira-sdk")

curupira_sdk-0.1.0.dev0/src/curupira_sdk/app.py

@@ -0,0 +1,180 @@
+"""Declarative Curupira extension application."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable
+from typing import Any, TypeVar, overload
+
+from .errors import RegistrationError, RpcError, SerializationError, ValidationError
+from .runtime import invoke, shutdown_runtime
+from .serialize import serialize_trigger_result
+from .server import ExtensionServer, serve_stdio
+from .signature import TriggerSpec, bind_arguments, build_trigger_spec, normalize_configuration
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class Curupira:
+    """Extension application that registers typed trigger functions."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        version: str,
+        agents: list[dict[str, Any]] | None = None,
+    ) -> None:
+        self.name = name
+        self.version = version
+        self.agents = agents or []
+        self._triggers: dict[str, TriggerSpec] = {}
+        self._agent_handlers: dict[str, Callable[[Any], Any]] = {}
+        self._lifecycle: dict[str, Callable[[Any], Any]] = {}
+        self._param_checks: dict[str, Callable[[dict[str, Any]], None]] = {}
+
+    @overload
+    def trigger(self, func: F) -> F: ...
+
+    @overload
+    def trigger(self, *, alias: str) -> Callable[[F], F]: ...
+
+    def trigger(
+        self, func: F | None = None, *, alias: str | None = None
+    ) -> F | Callable[[F], F]:
+        """Register ``func`` as a trigger.
+
+        Use ``@app.trigger`` with no parentheses to derive the local name from
+        ``func.__name__`` in kebab-case (``github_issues`` → ``github-issues``).
+        Use ``@app.trigger(alias="issues")`` to override the local name.
+
+        The host addresses triggers as ``<plugins-alias>/<local-name>`` after the
+        extension is registered under ``[plugins.<alias>]`` in settings TOML.
+        """
+
+        def decorator(fn: F) -> F:
+            spec = build_trigger_spec(fn, name=alias)
+            if spec.name in self._triggers:
+                raise RegistrationError(f"duplicate trigger name {spec.name!r}")
+            self._triggers[spec.name] = spec
+            return fn
+
+        if func is not None:
+            if alias is not None:
+                raise RegistrationError("use @app.trigger(alias=...) as a decorator factory")
+            return decorator(func)
+        return decorator
+
+    def param_check(
+        self, trigger_name: str, fn: Callable[[dict[str, Any]], None]
+    ) -> Callable[[dict[str, Any]], None]:
+        """Register an extra argument check run during validate and poll."""
+        self._param_checks[trigger_name] = fn
+        return fn
+
+    def on(self, method: str, handler: Callable[[Any], Any]) -> None:
+        """Register a low-level JSON-RPC handler (agent/lifecycle methods)."""
+        if method.startswith("agent/"):
+            self._agent_handlers[method] = handler
+        else:
+            self._lifecycle[method] = handler
+
+    def triggers(self) -> list[TriggerSpec]:
+        """Return registered trigger specs in registration order."""
+        return list(self._triggers.values())
+
+    def run(self) -> None:
+        """Serve the extension protocol on stdin/stdout until shutdown or EOF."""
+        server = ExtensionServer(
+            name=self.name,
+            version=self.version,
+            triggers=[
+                {"trigger_type": spec.name, "prompt_fields": list(spec.prompt_fields)}
+                for spec in self._triggers.values()
+            ],
+            agents=self.agents,
+        )
+        server.on("trigger/schema", self._handle_schema)
+        server.on("trigger/validate", self._handle_validate)
+        server.on("trigger/poll", self._handle_poll)
+        server.on("trigger/onStarted", self._handle_lifecycle("trigger/onStarted"))
+        server.on("trigger/onFinished", self._handle_lifecycle("trigger/onFinished"))
+        for method, handler in self._agent_handlers.items():
+            server.on(method, handler)
+        for method, handler in self._lifecycle.items():
+            if method not in {"trigger/onStarted", "trigger/onFinished"}:
+                server.on(method, handler)
+        try:
+            serve_stdio(server)
+        finally:
+            shutdown_runtime()
+
+    def print_manifest(self, manifest_template: str) -> None:
+        """Print a filled manifest template to stdout (for plugins install)."""
+        print(manifest_template.format(version=self.version, python=sys.executable))
+
+    def _get_spec(self, trigger_type: str) -> TriggerSpec:
+        # Host may send the namespaced form ``alias/local``; accept either.
+        local = trigger_type.rsplit("/", 1)[-1]
+        spec = self._triggers.get(local) or self._triggers.get(trigger_type)
+        if spec is None:
+            raise RpcError(-32003, f"unsupported trigger_type {trigger_type!r}")
+        return spec
+
+    def _handle_schema(self, params: Any) -> dict[str, Any]:
+        trigger_type = (params or {}).get("trigger_type")
+        if not isinstance(trigger_type, str):
+            raise RpcError(-32602, "trigger_type is required")
+        spec = self._get_spec(trigger_type)
+        return {"schema": spec.schema, "prompt_fields": list(spec.prompt_fields)}
+
+    def _handle_validate(self, params: Any) -> dict[str, Any]:
+        trigger_type = (params or {}).get("trigger_type")
+        configuration = dict((params or {}).get("configuration") or {})
+        if not isinstance(trigger_type, str):
+            raise RpcError(-32602, "trigger_type is required")
+        try:
+            spec = self._get_spec(trigger_type)
+            kwargs = bind_arguments(spec, configuration)
+            self._run_param_check(spec.name, kwargs)
+            normalized = normalize_configuration(spec, configuration)
+        except RpcError as exc:
+            return {"ok": False, "error": str(exc)}
+        except (ValidationError, RegistrationError) as exc:
+            return {"ok": False, "error": str(exc)}
+        return {"ok": True, "configuration": normalized}
+
+    def _run_param_check(self, trigger_name: str, kwargs: dict[str, Any]) -> None:
+        check = self._param_checks.get(trigger_name)
+        if check is not None:
+            check(kwargs)
+
+    def _handle_poll(self, params: Any) -> dict[str, Any]:
+        trigger_type = (params or {}).get("trigger_type")
+        automation = dict((params or {}).get("automation") or {})
+        if not isinstance(trigger_type, str):
+            raise RpcError(-32602, "trigger_type is required")
+        spec = self._get_spec(trigger_type)
+        try:
+            kwargs = bind_arguments(spec, automation)
+            self._run_param_check(spec.name, kwargs)
+            result = invoke(spec.func, kwargs, is_async=spec.is_async)
+            task = serialize_trigger_result(result, spec.return_annotation, trigger_name=spec.name)
+        except RpcError:
+            raise
+        except (ValidationError, SerializationError, RegistrationError) as exc:
+            raise RpcError(-32002, str(exc)) from exc
+        except Exception as exc:
+            raise RpcError(-32002, f"execution error: {exc}") from exc
+        return {"task": task}
+
+    def _handle_lifecycle(self, method: str) -> Callable[[Any], Any]:
+        custom = self._lifecycle.get(method)
+
+        def handler(params: Any) -> dict[str, Any]:
+            if custom is not None:
+                result = custom(params)
+                return result if isinstance(result, dict) else {}
+            return {}
+
+        return handler

curupira_sdk-0.1.0.dev0/src/curupira_sdk/errors.py

@@ -0,0 +1,26 @@
+"""SDK and JSON-RPC errors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class RegistrationError(Exception):
+    """Raised when a trigger cannot be registered."""
+
+
+class ValidationError(Exception):
+    """Raised when configuration or arguments fail validation."""
+
+
+class SerializationError(Exception):
+    """Raised when a trigger return value cannot be serialized."""
+
+
+class RpcError(Exception):
+    """JSON-RPC error with numeric code."""
+
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.data = data

curupira_sdk-0.1.0.dev0/src/curupira_sdk/framing.py

@@ -0,0 +1,39 @@
+"""Length-prefixed JSON frames (8 hex digits + body)."""
+
+from __future__ import annotations
+
+import sys
+from typing import BinaryIO
+
+DEFAULT_MAX_FRAME_BYTES = 16 * 1024 * 1024
+
+
+def write_frame(writer: BinaryIO, payload: bytes) -> None:
+    """Write one frame to a binary writer (typically stdout.buffer)."""
+    if len(payload) > 0xFFFFFFFF:
+        raise ValueError("frame too large")
+    writer.write(f"{len(payload):08x}".encode("ascii"))
+    writer.write(payload)
+    writer.flush()
+
+
+def read_frame(reader: BinaryIO, max_bytes: int = DEFAULT_MAX_FRAME_BYTES) -> bytes:
+    """Read one frame from a binary reader (typically stdin.buffer)."""
+    header = reader.read(8)
+    if len(header) < 8:
+        raise EOFError("unexpected EOF while reading frame header")
+    try:
+        length = int(header.decode("ascii"), 16)
+    except ValueError as exc:
+        raise ValueError("invalid frame header") from exc
+    if length > max_bytes:
+        raise ValueError(f"frame length {length} exceeds limit {max_bytes}")
+    body = reader.read(length)
+    if len(body) < length:
+        raise EOFError("unexpected EOF while reading frame body")
+    return body
+
+
+def log(message: str) -> None:
+    """Write a diagnostic line to stderr (never stdout)."""
+    print(message, file=sys.stderr, flush=True)

curupira_sdk-0.1.0.dev0/src/curupira_sdk/runtime.py

@@ -0,0 +1,39 @@
+"""Invoke synchronous and asynchronous trigger functions."""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+from typing import Any
+
+_LOOP: asyncio.AbstractEventLoop | None = None
+
+
+def get_event_loop() -> asyncio.AbstractEventLoop:
+    """Return a process-wide event loop for async triggers."""
+    global _LOOP
+    if _LOOP is None or _LOOP.is_closed():
+        _LOOP = asyncio.new_event_loop()
+        asyncio.set_event_loop(_LOOP)
+    return _LOOP
+
+
+def invoke(func: Any, kwargs: dict[str, Any], *, is_async: bool) -> Any:
+    """Call a sync or async function and return its result."""
+    if not is_async:
+        return func(**kwargs)
+
+    loop = get_event_loop()
+    if loop.is_running():
+        # Nested call from within a running loop: use a worker thread with its own loop.
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(asyncio.run, func(**kwargs)).result()
+    return loop.run_until_complete(func(**kwargs))
+
+
+def shutdown_runtime() -> None:
+    """Close the shared event loop if present."""
+    global _LOOP
+    if _LOOP is not None and not _LOOP.is_closed():
+        _LOOP.close()
+    _LOOP = None

curupira_sdk-0.1.0.dev0/src/curupira_sdk/serialize.py

@@ -0,0 +1,128 @@
+"""Validate and serialize a single trigger result or None."""
+
+from __future__ import annotations
+
+import collections.abc
+import dataclasses
+import types
+import typing
+from typing import Any, get_origin
+
+from .errors import SerializationError, ValidationError
+from .types import dump_value, is_collection_type, unwrap_optional
+
+
+def serialize_trigger_result(
+    value: Any, return_annotation: Any, *, trigger_name: str
+) -> dict[str, Any] | None:
+    """Return a host task envelope, or None when the trigger has no item."""
+    if _is_multi_value(value):
+        raise SerializationError(
+            f"trigger {trigger_name!r}: must return a single item or None, not a collection"
+        )
+
+    if value is None:
+        return None
+
+    if is_collection_type(return_annotation):
+        raise SerializationError(
+            f"trigger {trigger_name!r}: return annotation must not be a collection"
+        )
+
+    if return_annotation is not typing.Any and return_annotation is not None:
+        _validate_against_annotation(value, return_annotation, trigger_name=trigger_name)
+
+    try:
+        payload = dump_value(value)
+    except SerializationError as exc:
+        raise SerializationError(f"trigger {trigger_name!r}: {exc}") from exc
+
+    return envelope_from_payload(payload, trigger_name=trigger_name)
+
+
+def envelope_from_payload(payload: Any, *, trigger_name: str) -> dict[str, Any]:
+    """Build `{id, title, url, item}` for the Rust host."""
+    if isinstance(payload, (str, int, float, bool)):
+        text = str(payload)
+        return {"id": text, "title": text, "url": "", "item": {"value": payload}}
+
+    if not isinstance(payload, dict):
+        raise SerializationError(
+            f"trigger {trigger_name!r}: return value must serialize to an object or scalar"
+        )
+
+    item = dict(payload)
+    task_id = item.get("id")
+    if task_id is None and "number" in item:
+        task_id = item["number"]
+    if task_id is None:
+        raise SerializationError(
+            f"trigger {trigger_name!r}: return object must include an 'id' field "
+            "(or 'number' for issue-like items)"
+        )
+    title = item.get("title") or item.get("name") or str(task_id)
+    url = item.get("url") or ""
+    return {
+        "id": str(task_id),
+        "title": str(title),
+        "url": str(url),
+        "item": item,
+    }
+
+
+def _is_multi_value(value: Any) -> bool:
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return True
+    if isinstance(value, types.GeneratorType):
+        return True
+    return isinstance(value, collections.abc.Iterator) and not isinstance(
+        value, (str, bytes, dict, collections.abc.Mapping)
+    )
+
+
+def _validate_against_annotation(value: Any, annotation: Any, *, trigger_name: str) -> None:
+    from .types import coerce_value
+
+    inner, _allows_none = unwrap_optional(annotation)
+    origin = get_origin(inner)
+
+    if origin is list or origin is tuple or origin is set:
+        raise SerializationError(
+            f"trigger {trigger_name!r}: return annotation must not be a collection"
+        )
+
+    # Scalars: isinstance check.
+    if inner in {str, int, float, bool}:
+        if not isinstance(value, inner) or (inner is int and isinstance(value, bool)):
+            raise SerializationError(
+                f"trigger {trigger_name!r}: return value does not match annotation {annotation!r}"
+            )
+        return
+
+        # Exact instance of the annotated class is already valid.
+        if isinstance(inner, type) and isinstance(value, inner):
+            return
+
+        # Structured types: coerce via schema (dict / dataclass / pydantic / TypedDict).
+        try:
+            if dataclasses.is_dataclass(value) and not isinstance(value, type):
+                candidate: Any = dump_value(value)
+            elif _is_pydantic_instance(value):
+                candidate = dump_value(value)
+            elif isinstance(value, dict):
+                candidate = value
+            else:
+                candidate = value
+            coerce_value(annotation, candidate, context=f"trigger {trigger_name!r} return")
+        except (ValidationError, SerializationError) as exc:
+            raise SerializationError(
+                f"trigger {trigger_name!r}: return value incompatible with annotation: {exc}"
+            ) from exc
+
+
+def _is_pydantic_instance(value: Any) -> bool:
+    try:
+        from pydantic import BaseModel
+    except ImportError:
+        return False
+    return isinstance(value, BaseModel)