acty-langchain 0.1.0__tar.gz

acty_langchain-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+__pycache__/
+.coverage
+.mypy_cache/

acty_langchain-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Konstantin Polev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

acty_langchain-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: acty-langchain
+Version: 0.1.0
+Summary: LangChain helpers for acty payloads
+Project-URL: Homepage, https://github.com/conspol/acty-langchain
+Project-URL: Repository, https://github.com/conspol/acty-langchain
+Project-URL: Issues, https://github.com/conspol/acty-langchain/issues
+Maintainer-email: Konstantin Polev <70580603+conspol@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: langchain,messages,retry,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: acty-core<0.2.0,>=0.1.0
+Requires-Dist: langchain-core>=0.3.0
+Requires-Dist: tenacity>=8.2.0
+Provides-Extra: dev
+Requires-Dist: acty<0.2.0,>=0.1.0; extra == 'dev'
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.0; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# acty-langchain
+
+`acty-langchain` provides LangChain-specific helpers for the Acty ecosystem:
+message serialization, repair hints for malformed JSON outputs, and runnable
+executor utilities that integrate with `acty`.
+
+## Install
+
+Runtime helpers only:
+
+```bash
+pip install acty-langchain
+```
+
+If you want to run LangChain runnables through `ActyEngine`:
+
+```bash
+pip install acty acty-langchain
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Message Payload Helpers
+
+```python
+from langchain_core.messages import HumanMessage
+from acty_langchain import messages_to_acty_payload, messages_from_acty_payload
+
+payload = messages_to_acty_payload(
+    [HumanMessage(content="hello")],
+    payload={"exec_id": "chat"},
+)
+
+roundtrip = messages_from_acty_payload(payload)
+```
+
+These helpers convert LangChain messages into JSON-safe payload structures that
+can be stored, retried, or cached inside Acty workflows.
+
+## Runnable Payload Shape
+
+The runnable executor accepts payloads shaped like:
+
+```python
+{
+    "runnable": my_chain,
+    "input": {"question": "hi"},
+}
+```
+
+Resolver-based execution can also use:
+
+```python
+{
+    "exec_id": "qa",
+    "input": {"question": "hi"},
+}
+```
+
+## Runnable Execution
+
+```python
+from acty import ActyEngine, EngineConfig
+from acty_langchain import LangChainRunnableExecutor, runnable_retry_factory
+
+engine = ActyEngine(
+    executor=LangChainRunnableExecutor(),
+    config=EngineConfig(
+        attempt_retry_policy=runnable_retry_factory(),
+    ),
+)
+```
+
+## JSON Repair Helpers
+
+`acty-langchain` also includes repair utilities for invalid JSON responses:
+
+```python
+from acty_langchain import DefaultPromptedJsonRepairer
+
+repairer = DefaultPromptedJsonRepairer(
+    system_instruction="Return only valid JSON.",
+    repair_request="Please repair the assistant output above.",
+)
+```
+
+## Development
+
+- tests live under `tests/`
+- the package depends on `acty-core` at runtime
+- tests also install `acty` so runnable executor integration can be exercised

acty_langchain-0.1.0/README.md

@@ -0,0 +1,95 @@
+# acty-langchain
+
+`acty-langchain` provides LangChain-specific helpers for the Acty ecosystem:
+message serialization, repair hints for malformed JSON outputs, and runnable
+executor utilities that integrate with `acty`.
+
+## Install
+
+Runtime helpers only:
+
+```bash
+pip install acty-langchain
+```
+
+If you want to run LangChain runnables through `ActyEngine`:
+
+```bash
+pip install acty acty-langchain
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Message Payload Helpers
+
+```python
+from langchain_core.messages import HumanMessage
+from acty_langchain import messages_to_acty_payload, messages_from_acty_payload
+
+payload = messages_to_acty_payload(
+    [HumanMessage(content="hello")],
+    payload={"exec_id": "chat"},
+)
+
+roundtrip = messages_from_acty_payload(payload)
+```
+
+These helpers convert LangChain messages into JSON-safe payload structures that
+can be stored, retried, or cached inside Acty workflows.
+
+## Runnable Payload Shape
+
+The runnable executor accepts payloads shaped like:
+
+```python
+{
+    "runnable": my_chain,
+    "input": {"question": "hi"},
+}
+```
+
+Resolver-based execution can also use:
+
+```python
+{
+    "exec_id": "qa",
+    "input": {"question": "hi"},
+}
+```
+
+## Runnable Execution
+
+```python
+from acty import ActyEngine, EngineConfig
+from acty_langchain import LangChainRunnableExecutor, runnable_retry_factory
+
+engine = ActyEngine(
+    executor=LangChainRunnableExecutor(),
+    config=EngineConfig(
+        attempt_retry_policy=runnable_retry_factory(),
+    ),
+)
+```
+
+## JSON Repair Helpers
+
+`acty-langchain` also includes repair utilities for invalid JSON responses:
+
+```python
+from acty_langchain import DefaultPromptedJsonRepairer
+
+repairer = DefaultPromptedJsonRepairer(
+    system_instruction="Return only valid JSON.",
+    repair_request="Please repair the assistant output above.",
+)
+```
+
+## Development
+
+- tests live under `tests/`
+- the package depends on `acty-core` at runtime
+- tests also install `acty` so runnable executor integration can be exercised

acty_langchain-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "acty-langchain"
+version = "0.1.0"
+description = "LangChain helpers for acty payloads"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+maintainers = [{ name = "Konstantin Polev", email = "70580603+conspol@users.noreply.github.com" }]
+keywords = ["langchain", "messages", "retry", "workflow"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "acty-core>=0.1.0,<0.2.0",
+  "langchain-core>=0.3.0",
+  "tenacity>=8.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "acty>=0.1.0,<0.2.0",
+  "build>=1.2.2",
+  "pytest>=9.0.0",
+  "pytest-asyncio>=1.3.0",
+  "twine>=5.1.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/conspol/acty-langchain"
+Repository = "https://github.com/conspol/acty-langchain"
+Issues = "https://github.com/conspol/acty-langchain/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/acty_langchain"]

acty_langchain-0.1.0/pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+testpaths = tests
+pythonpath = src
+asyncio_mode = auto

acty_langchain-0.1.0/src/acty_langchain/__init__.py

@@ -0,0 +1,35 @@
+"""Helpers for LangChain integration with acty."""
+
+from .executor import (
+    LangChainRunnableExecutor,
+    make_langchain_executor,
+    runnable_retry_factory,
+    runnable_retry_payload_on_retry,
+)
+from .messages import (
+    from_acty_messages,
+    messages_from_acty_payload,
+    messages_to_acty_payload,
+    to_acty_messages,
+)
+from .repair_hints import format_json_parse_error, summarize_validation_errors
+from .repairer import DefaultPromptedJsonRepairer, PromptedJsonRepairer
+from .runnable import RetryPayloadFn, select_runnable_payload, validate_runnable_payload
+
+__all__ = [
+    "LangChainRunnableExecutor",
+    "make_langchain_executor",
+    "runnable_retry_factory",
+    "runnable_retry_payload_on_retry",
+    "from_acty_messages",
+    "messages_from_acty_payload",
+    "messages_to_acty_payload",
+    "to_acty_messages",
+    "format_json_parse_error",
+    "summarize_validation_errors",
+    "DefaultPromptedJsonRepairer",
+    "PromptedJsonRepairer",
+    "RetryPayloadFn",
+    "select_runnable_payload",
+    "validate_runnable_payload",
+]

acty_langchain-0.1.0/src/acty_langchain/executor.py

@@ -0,0 +1,271 @@
+"""LangChain runnable executor for acty payloads."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Awaitable, Callable, Mapping, TYPE_CHECKING
+
+from tenacity import AsyncRetrying, RetryCallState, stop_after_attempt
+
+from acty_core.core.types import Job, JobResult
+from acty_core.lifecycle import GroupLifecycleController
+
+from .runnable import validate_runnable_payload
+
+if TYPE_CHECKING:
+    from acty import ExecResolver
+    from acty_core.scheduler import TaggedExecutor
+
+RetryPayloadUpdate = Mapping[str, Any] | None
+RetryFactory = Callable[[Job], AsyncRetrying | Awaitable[AsyncRetrying]]
+# Callable registries may accept (exec_id) or (exec_id, job).
+RunnableRegistry = Mapping[str, Any] | Callable[[str], Any] | Callable[[str, Job], Any]
+
+
+def _build_registry_resolver(registry: RunnableRegistry):
+    """Build an ExecResolver for mapping or callable registries.
+
+    Callable registries may accept (exec_id) or (exec_id, job).
+    """
+    try:
+        from acty import CallableExecResolver, MappingExecResolver
+    except ImportError as exc:  # pragma: no cover - optional dependency
+        raise ImportError("make_langchain_executor requires acty to be installed") from exc
+    if callable(registry):
+        def _resolve(exec_id: str, job: Job) -> Any:
+            try:
+                sig = inspect.signature(registry)
+            except (TypeError, ValueError):
+                return registry(exec_id)
+            params = list(sig.parameters.values())
+            job_param = next((param for param in params if param.name == "job"), None)
+            if job_param is not None:
+                if job_param.kind == inspect.Parameter.POSITIONAL_ONLY:
+                    return registry(exec_id, job)
+                return registry(exec_id, job=job)
+            has_var_positional = any(param.kind == inspect.Parameter.VAR_POSITIONAL for param in params)
+            positional = [
+                param
+                for param in params
+                if param.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
+            ]
+            if has_var_positional or len(positional) >= 2:
+                return registry(exec_id, job)
+            return registry(exec_id)
+
+        return CallableExecResolver(_resolve)
+    return MappingExecResolver(registry)
+
+
+def make_langchain_executor(
+    *,
+    registry: RunnableRegistry | None = None,
+    resolver: "ExecResolver" | None = None,
+    allow_unwrapped_retry: bool = False,
+    **executor_kwargs: Any,
+) -> "TaggedExecutor":
+    """Return a ready-to-use LangChain executor, optionally wrapped with a resolver."""
+
+    if resolver is not None and registry is not None:
+        raise ValueError("Pass only one of resolver or registry")
+    if "runnable_registry" in executor_kwargs:
+        raise ValueError("Use registry/resolver with make_langchain_executor, not runnable_registry")
+
+    base = LangChainRunnableExecutor(
+        allow_unwrapped_retry=allow_unwrapped_retry,
+        **executor_kwargs,
+    )
+
+    if resolver is None and registry is not None:
+        resolver = _build_registry_resolver(registry)
+    if resolver is None:
+        return base
+    try:
+        from acty import ResolverExecutor
+    except ImportError as exc:  # pragma: no cover - optional dependency
+        raise ImportError("make_langchain_executor requires acty to be installed") from exc
+    return ResolverExecutor(base, resolver)
+
+
+class LangChainRunnableExecutor:
+    """Execute LangChain runnables from acty job payloads."""
+
+    handles_lifecycle = False
+    supports_executor_retry = False
+
+    def __init__(
+        self,
+        controller: GroupLifecycleController | None = None,
+        *,
+        allow_unwrapped_retry: bool = False,
+    ) -> None:
+        self._controller = controller
+        self._allow_unwrapped_retry = allow_unwrapped_retry
+
+    @classmethod
+    def with_registry(
+        cls,
+        registry: RunnableRegistry,
+        *,
+        resolver: "ExecResolver" | None = None,
+        allow_unwrapped_retry: bool = False,
+        **executor_kwargs: Any,
+    ) -> "TaggedExecutor":
+        """Build an executor wired to a registry via make_langchain_executor."""
+        return make_langchain_executor(
+            registry=registry,
+            resolver=resolver,
+            allow_unwrapped_retry=allow_unwrapped_retry,
+            **executor_kwargs,
+        )
+
+    def bind(self, controller: GroupLifecycleController) -> None:
+        self._controller = controller
+
+    async def execute(self, job: Job, *, pool: str) -> JobResult:
+        call_payload = validate_runnable_payload(job.payload)
+        if "runnable" not in call_payload:
+            raise RuntimeError(
+                "exec_id payloads require ResolverExecutor (use make_langchain_executor)"
+            )
+        retry = call_payload.get("retry")
+        if retry is not None and not self._allow_unwrapped_retry:
+            if not self.supports_executor_retry:
+                message = (
+                    "Payload retry requires EngineConfig.attempt_retry_policy "
+                    "(use runnable_retry_factory())"
+                )
+                if getattr(self, "_wrapper_forwarding_required", False):
+                    message = f"{message}; executor wrappers must forward supports_executor_retry"
+                raise RuntimeError(message)
+        output = await _invoke_runnable(call_payload)
+        return JobResult(
+            job_id=job.id,
+            kind=job.kind,
+            ok=True,
+            output=_wrap_output(output),
+            group_id=job.group_id,
+            follower_id=job.follower_id,
+        )
+
+    async def retry_payload_on_retry(self, retry_state: RetryCallState, job: Job) -> RetryPayloadUpdate:
+        """Apply retry_payload_fn to update payloads between retries."""
+        return await _runnable_retry_payload_on_retry(retry_state, job.payload, job.payload)
+
+
+def runnable_retry_factory(
+    *,
+    default_retry: AsyncRetrying | None = None,
+    resolver: "ExecResolver" | None = None,
+) -> RetryFactory:
+    """Return a tenacity retry factory that prefers per-job payload retry.
+
+    Returns a fresh AsyncRetrying instance per job by copying the selected retry
+    object. This isolates retry state across concurrent jobs, even if the caller
+    passes a shared instance.
+    """
+
+    if default_retry is None:
+        default_retry = AsyncRetrying(stop=stop_after_attempt(1))
+    if not isinstance(default_retry, AsyncRetrying):
+        raise ValueError("default_retry must be a tenacity.AsyncRetrying instance")
+
+    async def _factory_async(job: Job) -> AsyncRetrying:
+        try:
+            from acty import resolve_payload_with_exec_id
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise ImportError("runnable_retry_factory resolver support requires acty to be installed") from exc
+
+        payload = resolve_payload_with_exec_id(job.payload, resolver, job=job)
+        if inspect.isawaitable(payload):
+            payload = await payload
+        call_payload = validate_runnable_payload(payload)
+        if "runnable" not in call_payload:
+            raise RuntimeError("exec_id payloads require ResolverExecutor to inject a runnable")
+        retry = call_payload.get("retry") or default_retry
+        if not isinstance(retry, AsyncRetrying):
+            raise ValueError("retry must be a tenacity.AsyncRetrying instance")
+        return retry.copy()
+
+    def _factory(job: Job) -> AsyncRetrying:
+        call_payload = validate_runnable_payload(job.payload)
+        if "runnable" not in call_payload:
+            raise RuntimeError("exec_id payloads require resolver in runnable_retry_factory")
+        retry = call_payload.get("retry") or default_retry
+        if not isinstance(retry, AsyncRetrying):
+            raise ValueError("retry must be a tenacity.AsyncRetrying instance")
+        return retry.copy()
+
+    return _factory_async if resolver is not None else _factory
+
+
+async def runnable_retry_payload_on_retry(retry_state: RetryCallState, job: Job) -> RetryPayloadUpdate:
+    """Apply payload retry_payload_fn to update payloads between retries."""
+    return await _runnable_retry_payload_on_retry(retry_state, job.payload, job.payload)
+
+
+async def _runnable_retry_payload_on_retry(
+    retry_state: RetryCallState,
+    job_payload: Mapping[str, Any] | Any,
+    call_payload: Mapping[str, Any] | Any,
+) -> RetryPayloadUpdate:
+    """Internal helper that allows resolving payloads separately from stored metadata."""
+
+    outcome = retry_state.outcome
+    if outcome is None or not outcome.failed:
+        return None
+    exc = outcome.exception()
+    if exc is None or not isinstance(exc, Exception):
+        return None
+
+    call_payload_map = validate_runnable_payload(call_payload)
+    retry_payload_fn = call_payload_map.get("retry_payload_fn")
+    if retry_payload_fn is None:
+        return None
+
+    maybe_new = retry_payload_fn(retry_state.attempt_number, exc, call_payload_map)
+    if inspect.isawaitable(maybe_new):
+        maybe_new = await maybe_new
+    if maybe_new is None:
+        return None
+    if not isinstance(maybe_new, Mapping):
+        raise ValueError("retry_payload_fn must return a mapping")
+
+    new_payload = dict(maybe_new)
+    if "retry" not in new_payload and call_payload_map.get("retry") is not None:
+        new_payload["retry"] = call_payload_map.get("retry")
+    if "retry_payload_fn" not in new_payload and call_payload_map.get("retry_payload_fn") is not None:
+        new_payload["retry_payload_fn"] = call_payload_map.get("retry_payload_fn")
+
+    if isinstance(job_payload, Mapping) and "runnable" not in job_payload and "payload" in job_payload:
+        merged = dict(job_payload)
+        merged["payload"] = new_payload
+        validate_runnable_payload(merged)
+        return merged
+    if isinstance(job_payload, Mapping) and "exec_id" in job_payload and "exec_id" not in new_payload:
+        merged = dict(new_payload)
+        merged["exec_id"] = job_payload["exec_id"]
+        validate_runnable_payload(merged)
+        return merged
+    validate_runnable_payload(new_payload)
+    return new_payload
+
+
+async def _invoke_runnable(call_payload: Mapping[str, Any]) -> Any:
+    if "runnable" not in call_payload:
+        raise ValueError("Runnable payload must include 'runnable'")
+    runnable = call_payload["runnable"]
+    input_payload = call_payload["input"]
+    config = call_payload.get("config")
+    if hasattr(runnable, "ainvoke"):
+        return await runnable.ainvoke(input_payload, config=config)
+    if hasattr(runnable, "invoke"):
+        return await asyncio.to_thread(runnable.invoke, input_payload, config=config)
+    raise ValueError("Runnable does not support invoke/ainvoke")
+
+
+def _wrap_output(output: Any) -> Mapping[str, Any]:
+    if isinstance(output, Mapping):
+        return output
+    return {"output": output}

acty_langchain-0.1.0/src/acty_langchain/messages.py

@@ -0,0 +1,82 @@
+"""LangChain message serialization helpers for acty payloads."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping, Sequence
+
+_LANGCHAIN_CACHE: tuple[type, Any, Any] | None = None
+
+
+def _load_langchain():
+    global _LANGCHAIN_CACHE
+    if _LANGCHAIN_CACHE is not None:
+        return _LANGCHAIN_CACHE
+    try:
+        from langchain_core.messages import BaseMessage, messages_from_dict, messages_to_dict
+    except ImportError as exc:  # pragma: no cover - dependency is optional
+        raise ImportError(
+            "acty-langchain requires langchain-core to be installed"
+        ) from exc
+    _LANGCHAIN_CACHE = (BaseMessage, messages_from_dict, messages_to_dict)
+    return _LANGCHAIN_CACHE
+
+
+def _is_serialized_message(item: Mapping[str, Any]) -> bool:
+    return "type" in item and "data" in item
+
+
+def to_acty_messages(
+    messages: Iterable[Any] | Sequence[Mapping[str, Any]],
+) -> list[dict[str, Any]]:
+    """Convert LangChain messages to JSON-safe dicts for acty payloads.
+
+    Accepts either BaseMessage objects or already-serialized dicts produced
+    by langchain_core.messages.messages_to_dict.
+    """
+    items = list(messages)
+    if not items:
+        return []
+
+    if isinstance(items[0], Mapping):
+        if not all(isinstance(m, Mapping) and _is_serialized_message(m) for m in items):
+            raise ValueError("Serialized messages must be dicts with 'type' and 'data'")
+        return [dict(m) for m in items]
+
+    BaseMessage, _messages_from_dict, messages_to_dict = _load_langchain()
+    if not all(isinstance(m, BaseMessage) for m in items):
+        raise ValueError("Expected BaseMessage objects or serialized dicts")
+    return messages_to_dict(items)
+
+
+def from_acty_messages(messages: Iterable[Mapping[str, Any]]) -> list[Any]:
+    """Convert serialized LangChain message dicts back to BaseMessage objects."""
+    items = list(messages)
+    if not items:
+        return []
+    if not all(isinstance(m, Mapping) and _is_serialized_message(m) for m in items):
+        raise ValueError("Serialized messages must be dicts with 'type' and 'data'")
+    BaseMessage, messages_from_dict, _messages_to_dict = _load_langchain()
+    return messages_from_dict(items)
+
+
+def messages_to_acty_payload(
+    messages: Iterable[Any] | Sequence[Mapping[str, Any]],
+    *,
+    key: str = "messages",
+    payload: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Attach serialized LangChain messages under payload[key]."""
+    base = dict(payload or {})
+    base[key] = to_acty_messages(messages)
+    return base
+
+
+def messages_from_acty_payload(
+    payload: Mapping[str, Any],
+    *,
+    key: str = "messages",
+) -> list[Any]:
+    """Extract LangChain messages from payload[key]."""
+    if key not in payload:
+        raise KeyError(f"payload missing '{key}'")
+    return from_acty_messages(payload[key])