acty-openai 0.1.0__tar.gz

acty_openai-0.1.0/.gitignore

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

acty_openai-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_openai-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: acty-openai
+Version: 0.1.0
+Summary: OpenAI executor for acty
+Project-URL: Homepage, https://github.com/conspol/acty-openai
+Project-URL: Repository, https://github.com/conspol/acty-openai
+Project-URL: Issues, https://github.com/conspol/acty-openai/issues
+Maintainer-email: Konstantin Polev <70580603+conspol@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: langchain,openai,telemetry,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: acty<0.2.0,>=0.1.0
+Requires-Dist: langchain-openai>=0.2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: opentelemetry-sdk>=1.39.0; 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-openai
+
+`acty-openai` provides an `OpenAIExecutor` implementation for Acty. It adapts
+`langchain-openai` chat models to the Acty executor interface and emits the
+shared telemetry attributes used across the wider Acty stack.
+
+## Install
+
+```bash
+pip install acty-openai
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Usage
+
+```python
+import asyncio
+
+from acty import ActyEngine, EngineConfig
+from acty_openai import OpenAIExecutor
+from langchain_openai import ChatOpenAI
+
+
+async def main() -> None:
+    model = ChatOpenAI(model="gpt-4o-mini")
+    engine = ActyEngine(
+        executor=OpenAIExecutor(model=model),
+        config=EngineConfig(primer_workers=1, follower_workers=1),
+    )
+    try:
+        payload = {
+            "messages": [{"role": "user", "content": "hello"}],
+        }
+        submission = await engine.submit_group("demo", payload, [])
+        if submission.primer is not None:
+            result = await submission.primer
+            print(result.output)
+    finally:
+        await engine.close()
+
+
+asyncio.run(main())
+```
+
+## Notes
+
+- if you do not pass a model explicitly, `OpenAIExecutor` requires `langchain-openai`
+- the executor can attach OpenTelemetry span attributes when telemetry is enabled
+- this package depends directly on both `acty` and `acty-core` because it imports both at runtime
+
+## Development
+
+- tests live under `tests/`
+- the repo includes unit tests plus an Acty engine integration test for shared telemetry behavior

acty_openai-0.1.0/README.md

@@ -0,0 +1,59 @@
+# acty-openai
+
+`acty-openai` provides an `OpenAIExecutor` implementation for Acty. It adapts
+`langchain-openai` chat models to the Acty executor interface and emits the
+shared telemetry attributes used across the wider Acty stack.
+
+## Install
+
+```bash
+pip install acty-openai
+```
+
+For local development:
+
+```bash
+pip install -e .[dev]
+```
+
+## Usage
+
+```python
+import asyncio
+
+from acty import ActyEngine, EngineConfig
+from acty_openai import OpenAIExecutor
+from langchain_openai import ChatOpenAI
+
+
+async def main() -> None:
+    model = ChatOpenAI(model="gpt-4o-mini")
+    engine = ActyEngine(
+        executor=OpenAIExecutor(model=model),
+        config=EngineConfig(primer_workers=1, follower_workers=1),
+    )
+    try:
+        payload = {
+            "messages": [{"role": "user", "content": "hello"}],
+        }
+        submission = await engine.submit_group("demo", payload, [])
+        if submission.primer is not None:
+            result = await submission.primer
+            print(result.output)
+    finally:
+        await engine.close()
+
+
+asyncio.run(main())
+```
+
+## Notes
+
+- if you do not pass a model explicitly, `OpenAIExecutor` requires `langchain-openai`
+- the executor can attach OpenTelemetry span attributes when telemetry is enabled
+- this package depends directly on both `acty` and `acty-core` because it imports both at runtime
+
+## Development
+
+- tests live under `tests/`
+- the repo includes unit tests plus an Acty engine integration test for shared telemetry behavior

acty_openai-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "acty-openai"
+version = "0.1.0"
+description = "OpenAI executor for acty"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+maintainers = [{ name = "Konstantin Polev", email = "70580603+conspol@users.noreply.github.com" }]
+keywords = ["openai", "langchain", "telemetry", "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>=0.1.0,<0.2.0",
+  "acty-core>=0.1.0,<0.2.0",
+  "langchain-openai>=0.2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.2",
+  "opentelemetry-sdk>=1.39.0",
+  "pytest>=9.0.0",
+  "pytest-asyncio>=1.3.0",
+  "twine>=5.1.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/conspol/acty-openai"
+Repository = "https://github.com/conspol/acty-openai"
+Issues = "https://github.com/conspol/acty-openai/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/acty_openai"]

acty_openai-0.1.0/pytest.ini

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

acty_openai-0.1.0/src/acty_openai/__init__.py

@@ -0,0 +1,15 @@
+"""OpenAI executor for acty."""
+
+from .executor import (
+    OpenAIErrorCategory,
+    OpenAIExecutor,
+    classify_openai_error,
+    make_openai_executor,
+)
+
+__all__ = [
+    "OpenAIErrorCategory",
+    "OpenAIExecutor",
+    "classify_openai_error",
+    "make_openai_executor",
+]

acty_openai-0.1.0/src/acty_openai/executor.py

@@ -0,0 +1,506 @@
+"""OpenAI executor for acty."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from enum import Enum
+from typing import Any, Awaitable, Callable, Mapping, Sequence
+
+from acty_core.core.types import Job, JobResult
+from acty_core.lifecycle import GroupLifecycleController
+from acty_core.telemetry import TelemetryPrivacyConfig
+from acty_core.telemetry import llm_messages as llm_message_utils
+from acty_core.telemetry.acty_span import build_acty_span_attributes
+from acty_core.telemetry.llm_messages import (
+    extract_input_messages as shared_extract_input_messages,
+    flatten_batched_messages as shared_flatten_batched_messages,
+    flatten_messages as shared_flatten_messages,
+)
+from acty_core.telemetry.llm_tokens import cached_token_attributes as shared_cached_token_attributes
+
+try:  # Optional OpenTelemetry dependency.
+    from opentelemetry import trace as otel_trace
+except Exception:  # pragma: no cover - optional dependency
+    otel_trace = None
+
+logger = logging.getLogger(__name__)
+
+
+def _is_openrouter_base_url(value: Any) -> bool:
+    if value is None:
+        return False
+    try:
+        text = str(value).lower()
+    except Exception:
+        return False
+    return "openrouter.ai" in text
+
+
+def _extract_base_url_from_model(model: Any) -> str | None:
+    for attr in ("openai_api_base", "openai_base_url", "base_url", "api_base"):
+        value = getattr(model, attr, None)
+        if value:
+            return str(value)
+    for client_attr in ("client", "async_client"):
+        client = getattr(model, client_attr, None)
+        if client is None:
+            continue
+        value = getattr(client, "base_url", None)
+        if value:
+            return str(value)
+    return None
+
+
+def _infer_llm_system(
+    model: Any,
+    invoke_kwargs: Mapping[str, Any],
+    model_kwargs: Mapping[str, Any] | None,
+) -> str | None:
+    base_url = None
+    if isinstance(model_kwargs, Mapping):
+        base_url = model_kwargs.get("base_url") or model_kwargs.get("openai_api_base")
+    if base_url is None and isinstance(invoke_kwargs, Mapping):
+        base_url = invoke_kwargs.get("base_url") or invoke_kwargs.get("openai_api_base")
+    if base_url is None:
+        base_url = _extract_base_url_from_model(model)
+    if _is_openrouter_base_url(base_url):
+        return "openrouter"
+    return None
+
+
+def _apply_gateway_attributes(
+    span: Any,
+    *,
+    system: str | None,
+) -> None:
+    if not system:
+        return
+    span.set_attribute("gen_ai.system", system)
+    span.set_attribute("llm.system", system)
+    span.set_attribute("llm.provider", system)
+
+
+class OpenAIErrorCategory(Enum):
+    TRANSIENT = "transient"
+    FATAL = "fatal"
+
+
+OpenAIErrorClassifier = Callable[[BaseException], OpenAIErrorCategory]
+
+
+def classify_openai_error(exc: BaseException) -> OpenAIErrorCategory:
+    status_code = _extract_status_code(exc)
+    if status_code in {401, 403}:
+        return OpenAIErrorCategory.FATAL
+    if status_code in {408, 409, 425, 429, 500, 502, 503, 504}:
+        return OpenAIErrorCategory.TRANSIENT
+
+    try:
+        import openai  # type: ignore
+    except Exception:  # pragma: no cover - optional dependency
+        openai = None
+    if openai is not None:
+        for name in ("AuthenticationError", "PermissionDeniedError"):
+            cls = getattr(openai, name, None)
+            if cls is not None and isinstance(exc, cls):
+                return OpenAIErrorCategory.FATAL
+        for name in (
+            "RateLimitError",
+            "APITimeoutError",
+            "APIConnectionError",
+            "InternalServerError",
+            "ServiceUnavailableError",
+        ):
+            cls = getattr(openai, name, None)
+            if cls is not None and isinstance(exc, cls):
+                return OpenAIErrorCategory.TRANSIENT
+
+    try:
+        import httpx  # type: ignore
+    except Exception:
+        httpx = None
+    if httpx is not None and isinstance(exc, httpx.RequestError):
+        return OpenAIErrorCategory.TRANSIENT
+    try:
+        import httpcore  # type: ignore
+    except Exception:
+        httpcore = None
+    if httpcore is not None and isinstance(
+        exc,
+        (
+            httpcore.NetworkError,
+            httpcore.TimeoutException,
+            httpcore.ProxyError,
+        ),
+    ):
+        return OpenAIErrorCategory.TRANSIENT
+
+    if isinstance(exc, (TimeoutError, ConnectionError, OSError, asyncio.TimeoutError)):
+        return OpenAIErrorCategory.TRANSIENT
+
+    message = str(exc).lower()
+    if any(
+        keyword in message
+        for keyword in (
+            "timeout",
+            "timed out",
+            "rate limit",
+            "too many requests",
+            "temporarily",
+            "unavailable",
+            "connection",
+            "overloaded",
+            "try again",
+            "authentication",
+            "unauthorized",
+            "api key",
+            "permission denied",
+        )
+    ):
+        if any(term in message for term in ("unauthorized", "api key", "permission", "authentication")):
+            return OpenAIErrorCategory.FATAL
+        return OpenAIErrorCategory.TRANSIENT
+
+    return OpenAIErrorCategory.TRANSIENT
+
+
+class OpenAIExecutor:
+    """Execute OpenAI-compatible LangChain calls from acty job payloads."""
+
+    handles_lifecycle = False
+    supports_executor_retry = False
+
+    def __init__(
+        self,
+        controller: GroupLifecycleController | None = None,
+        *,
+        model: Any | None = None,
+        model_factory: Callable[[], Any] | None = None,
+        model_kwargs: Mapping[str, Any] | None = None,
+        error_classifier: OpenAIErrorClassifier | None = None,
+        span_enrichment: bool = True,
+        max_messages: int = 20,
+        max_message_chars: int = 4096,
+        emit_batched_messages: bool = False,
+        telemetry_privacy: TelemetryPrivacyConfig | None = None,
+    ) -> None:
+        if model is not None and model_factory is not None:
+            raise ValueError("Provide either model or model_factory, not both")
+        self._controller = controller
+        self._model = model
+        self._model_factory = model_factory
+        self._model_kwargs = dict(model_kwargs) if model_kwargs else None
+        self._error_classifier = error_classifier
+        self._span_enrichment = bool(span_enrichment)
+        self._max_messages = max(0, int(max_messages))
+        self._max_message_chars = max(0, int(max_message_chars))
+        self._emit_batched_messages = bool(emit_batched_messages)
+        self._telemetry_privacy = telemetry_privacy or TelemetryPrivacyConfig()
+
+    def bind(self, controller: GroupLifecycleController) -> None:
+        self._controller = controller
+
+    def bind_telemetry_privacy(self, telemetry_privacy: TelemetryPrivacyConfig) -> None:
+        self._telemetry_privacy = telemetry_privacy
+
+    async def execute(self, job: Job, *, pool: str) -> JobResult:  # noqa: ARG002 - pool kept for interface
+        call_input, invoke_kwargs = _resolve_call(job.payload)
+        model = self._get_model()
+        span = None
+        if self._span_enrichment:
+            span = _get_recording_span(log_missing=True)
+            if span is not None:
+                _apply_acty_span_attributes(span, job, invoke_kwargs)
+                system = _infer_llm_system(model, invoke_kwargs, self._model_kwargs)
+                _apply_gateway_attributes(span, system=system)
+                _apply_input_message_attributes(
+                    span,
+                    job.payload,
+                    call_input,
+                    max_messages=self._max_messages,
+                    max_message_chars=self._max_message_chars,
+                    emit_batched_messages=self._emit_batched_messages,
+                    telemetry_privacy=self._telemetry_privacy,
+                )
+        try:
+            result = await _invoke_model(model, call_input, invoke_kwargs)
+        except Exception as exc:
+            category = self._classify_error(exc)
+            _attach_error_category(exc, category)
+            raise
+        if self._span_enrichment:
+            span_after = _get_recording_span(log_missing=False)
+            target_span = span_after or span
+            if target_span is not None:
+                if span is None and span_after is not None:
+                    _apply_acty_span_attributes(target_span, job, invoke_kwargs)
+                    system = _infer_llm_system(model, invoke_kwargs, self._model_kwargs)
+                    _apply_gateway_attributes(target_span, system=system)
+                    _apply_input_message_attributes(
+                        target_span,
+                        job.payload,
+                        call_input,
+                        max_messages=self._max_messages,
+                        max_message_chars=self._max_message_chars,
+                        emit_batched_messages=self._emit_batched_messages,
+                        telemetry_privacy=self._telemetry_privacy,
+                    )
+                else:
+                    system = _infer_llm_system(model, invoke_kwargs, self._model_kwargs)
+                    _apply_gateway_attributes(target_span, system=system)
+                _apply_cached_token_attributes(target_span, result)
+        return JobResult(
+            job_id=job.id,
+            kind=job.kind,
+            ok=True,
+            output={"result": result},
+            group_id=job.group_id,
+            follower_id=job.follower_id,
+        )
+
+    def _get_model(self) -> Any:
+        if self._model is not None:
+            return self._model
+        if self._model_factory is not None:
+            self._model = self._model_factory()
+            return self._model
+        try:
+            from langchain_openai import ChatOpenAI
+        except ImportError as exc:  # pragma: no cover - optional dependency
+            raise ImportError("langchain-openai is required when model is not provided") from exc
+        kwargs = dict(self._model_kwargs) if self._model_kwargs else {}
+        self._model = ChatOpenAI(**kwargs)
+        return self._model
+
+    def _classify_error(self, exc: BaseException) -> OpenAIErrorCategory:
+        classifier = self._error_classifier or classify_openai_error
+        try:
+            return classifier(exc)
+        except Exception:
+            logger.debug("openai_error_classification_failed", exc_info=True)
+            return OpenAIErrorCategory.TRANSIENT
+
+
+def make_openai_executor(
+    *,
+    model: Any | None = None,
+    model_factory: Callable[[], Any] | None = None,
+    model_kwargs: Mapping[str, Any] | None = None,
+    error_classifier: OpenAIErrorClassifier | None = None,
+    span_enrichment: bool = True,
+    max_messages: int = 20,
+    max_message_chars: int = 4096,
+    emit_batched_messages: bool = False,
+    telemetry_privacy: TelemetryPrivacyConfig | None = None,
+) -> OpenAIExecutor:
+    """Factory helper for a configured OpenAI executor."""
+    return OpenAIExecutor(
+        model=model,
+        model_factory=model_factory,
+        model_kwargs=model_kwargs,
+        error_classifier=error_classifier,
+        span_enrichment=span_enrichment,
+        max_messages=max_messages,
+        max_message_chars=max_message_chars,
+        emit_batched_messages=emit_batched_messages,
+        telemetry_privacy=telemetry_privacy,
+    )
+
+
+def _resolve_call(payload: Any) -> tuple[Any, Mapping[str, Any]]:
+    if not isinstance(payload, Mapping):
+        return payload, {}
+
+    invoke_kwargs = payload.get("invoke_kwargs")
+    candidate: Any = payload
+    if "payload" in payload and not any(key in payload for key in ("messages", "input", "prompt")):
+        inner = payload.get("payload")
+        if isinstance(inner, Mapping):
+            candidate = inner
+        else:
+            if isinstance(invoke_kwargs, Mapping):
+                return inner, invoke_kwargs
+            return inner, {}
+
+    if isinstance(candidate, Mapping):
+        if "messages" in candidate:
+            call_input = candidate["messages"]
+        elif "input" in candidate:
+            call_input = candidate["input"]
+        elif "prompt" in candidate:
+            call_input = candidate["prompt"]
+        else:
+            call_input = candidate
+        if not isinstance(invoke_kwargs, Mapping):
+            invoke_kwargs = candidate.get("invoke_kwargs")
+    else:
+        call_input = candidate
+
+    if isinstance(invoke_kwargs, Mapping):
+        return call_input, invoke_kwargs
+    return call_input, {}
+
+
+async def _invoke_model(model: Any, call_input: Any, invoke_kwargs: Mapping[str, Any]) -> Any:
+    if hasattr(model, "ainvoke"):
+        result = model.ainvoke(call_input, **invoke_kwargs)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+    if hasattr(model, "invoke"):
+        result = model.invoke(call_input, **invoke_kwargs)
+        if inspect.isawaitable(result):
+            return await result
+        return result
+    raise TypeError("Model must provide invoke or ainvoke")
+
+
+def _extract_status_code(exc: BaseException) -> int | None:
+    for attr in ("status_code", "status", "http_status", "code"):
+        value = getattr(exc, attr, None)
+        if isinstance(value, int):
+            return value
+    response = getattr(exc, "response", None)
+    if response is not None:
+        for attr in ("status_code", "status"):
+            value = getattr(response, attr, None)
+            if isinstance(value, int):
+                return value
+    return None
+
+
+def _get_recording_span(*, log_missing: bool) -> Any | None:
+    if otel_trace is None:
+        if log_missing:
+            logger.warning("LLM span enrichment skipped: OpenTelemetry unavailable.")
+        return None
+    span = otel_trace.get_current_span()
+    if span is None or not span.is_recording():
+        if log_missing:
+            logger.warning("LLM span enrichment skipped: current span not recording.")
+        return None
+    return span
+
+
+def _apply_acty_span_attributes(
+    span: Any,
+    job: Job,
+    invoke_kwargs: Mapping[str, Any],
+) -> None:
+    attributes = build_acty_span_attributes(job, invoke_kwargs)
+    _set_span_attributes(span, attributes)
+
+
+def _apply_input_message_attributes(
+    span: Any,
+    payload: Any,
+    call_input: Any,
+    *,
+    max_messages: int,
+    max_message_chars: int,
+    emit_batched_messages: bool = False,
+    telemetry_privacy: TelemetryPrivacyConfig | None = None,
+) -> None:
+    if not _should_emit_input_messages(telemetry_privacy):
+        return
+    messages, batch_selected = _extract_input_messages(
+        payload,
+        call_input,
+        emit_batched_messages=emit_batched_messages,
+    )
+    if messages is None:
+        return
+    if _looks_like_message_batch(messages):
+        attributes = _flatten_batched_messages(
+            messages,
+            max_messages=max_messages,
+            max_message_chars=max_message_chars,
+        )
+    else:
+        attributes = _flatten_messages(
+            messages,
+            max_messages=max_messages,
+            max_message_chars=max_message_chars,
+        )
+    if batch_selected is not None:
+        attributes["acty.message_batch_selected"] = batch_selected
+    _set_span_attributes(span, attributes)
+
+
+def _should_emit_input_messages(telemetry_privacy: TelemetryPrivacyConfig | None = None) -> bool:
+    policy = telemetry_privacy or TelemetryPrivacyConfig()
+    return policy.should_emit_input_messages()
+
+
+def _extract_input_messages(
+    payload: Any,
+    call_input: Any,
+    *,
+    emit_batched_messages: bool,
+) -> tuple[Sequence[Any] | Sequence[Sequence[Any]] | None, int | None]:
+    return shared_extract_input_messages(
+        payload,
+        call_input,
+        emit_batched_messages=emit_batched_messages,
+    )
+
+
+def _looks_like_message_batch(value: Any) -> bool:
+    return llm_message_utils._looks_like_message_batch(value)
+
+
+def _flatten_messages(
+    messages: Sequence[Any],
+    *,
+    max_messages: int,
+    max_message_chars: int,
+) -> dict[str, Any]:
+    return shared_flatten_messages(
+        messages,
+        max_messages=max_messages,
+        max_message_chars=max_message_chars,
+    )
+
+
+def _flatten_batched_messages(
+    batches: Sequence[Sequence[Any]],
+    *,
+    max_messages: int,
+    max_message_chars: int,
+) -> dict[str, Any]:
+    return shared_flatten_batched_messages(
+        batches,
+        max_messages=max_messages,
+        max_message_chars=max_message_chars,
+    )
+
+
+def _apply_cached_token_attributes(span: Any, output: Any) -> None:
+    attributes = shared_cached_token_attributes(output)
+    if not attributes:
+        return
+    _set_span_attributes(span, attributes)
+
+
+def _set_span_attributes(span: Any, attributes: Mapping[str, Any]) -> None:
+    for key, value in attributes.items():
+        if value is None:
+            continue
+        span.set_attribute(key, value)
+
+
+def _attach_error_category(exc: BaseException, category: OpenAIErrorCategory) -> None:
+    try:
+        setattr(exc, "acty_error_category", category.value)
+    except Exception:
+        return
+
+
+__all__ = [
+    "OpenAIErrorCategory",
+    "OpenAIExecutor",
+    "classify_openai_error",
+    "make_openai_executor",
+]

acty_openai-0.1.0/tests/test_error_classification.py

@@ -0,0 +1,19 @@
+from acty_openai.executor import OpenAIErrorCategory, classify_openai_error
+
+
+class DummyError(Exception):
+    def __init__(self, status_code: int | None = None, message: str = "") -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def test_classify_openai_error_status_codes() -> None:
+    assert classify_openai_error(DummyError(status_code=401)) is OpenAIErrorCategory.FATAL
+    assert classify_openai_error(DummyError(status_code=403)) is OpenAIErrorCategory.FATAL
+    assert classify_openai_error(DummyError(status_code=429)) is OpenAIErrorCategory.TRANSIENT
+    assert classify_openai_error(DummyError(status_code=503)) is OpenAIErrorCategory.TRANSIENT
+
+
+def test_classify_openai_error_message_fallbacks() -> None:
+    assert classify_openai_error(DummyError(message="rate limit exceeded")) is OpenAIErrorCategory.TRANSIENT
+    assert classify_openai_error(DummyError(message="authentication failed")) is OpenAIErrorCategory.FATAL

acty_openai-0.1.0/tests/test_executor.py

@@ -0,0 +1,96 @@
+from dataclasses import dataclass
+
+import pytest
+
+from acty_core.core.types import GroupId, Job, JobId
+from acty_openai import OpenAIExecutor
+import acty_openai.executor as executor_module
+
+
+class DummyModel:
+    def __init__(self) -> None:
+        self.calls = []
+
+    async def ainvoke(self, call_input, **kwargs):
+        self.calls.append((call_input, kwargs))
+        return "ok"
+
+
+@dataclass
+class DummyMessage:
+    role: str
+    content: str
+    name: str | None = None
+    additional_kwargs: dict | None = None
+
+
+@pytest.mark.asyncio
+async def test_executor_invokes_model_with_input() -> None:
+    model = DummyModel()
+    executor = OpenAIExecutor(model=model, span_enrichment=False)
+    job = Job(
+        id=JobId("job-1"),
+        kind="task",
+        payload={"input": "hi", "invoke_kwargs": {"temperature": 0}},
+        group_id=GroupId("g1"),
+    )
+
+    result = await executor.execute(job, pool="p1")
+    assert result.ok is True
+    assert result.output == {"result": "ok"}
+    assert model.calls == [("hi", {"temperature": 0})]
+
+
+@pytest.mark.asyncio
+async def test_executor_unwraps_acty_payload_wrapper() -> None:
+    model = DummyModel()
+    executor = OpenAIExecutor(model=model, span_enrichment=False)
+    job = Job(
+        id=JobId("job-2"),
+        kind="task",
+        payload={"payload": {"messages": [{"role": "user", "content": "hi"}]}},
+        group_id=GroupId("g2"),
+    )
+
+    result = await executor.execute(job, pool="p1")
+    assert result.ok is True
+    assert model.calls == [([{"role": "user", "content": "hi"}], {})]
+
+
+def test_extract_input_messages_batch_selection() -> None:
+    payload = {
+        "messages": [
+            [{"role": "user", "content": "hi"}],
+            [{"role": "user", "content": "bye"}],
+        ]
+    }
+    messages, batch_selected = executor_module._extract_input_messages(
+        payload,
+        payload["messages"],
+        emit_batched_messages=False,
+    )
+    assert messages == [{"role": "user", "content": "hi"}]
+    assert batch_selected == 0
+
+    messages, batch_selected = executor_module._extract_input_messages(
+        payload,
+        payload["messages"],
+        emit_batched_messages=True,
+    )
+    assert messages == payload["messages"]
+    assert batch_selected is None
+
+
+def test_flatten_messages_handles_mapping_and_object() -> None:
+    messages = [
+        {"role": "user", "content": "hi", "additional_kwargs": {"tool_call_id": "tool-1"}},
+        DummyMessage(role="assistant", content="ok", name="helper"),
+    ]
+    attrs = executor_module._flatten_messages(messages, max_messages=10, max_message_chars=100)
+
+    assert attrs["llm.input_messages.0.message.role"] == "user"
+    assert attrs["llm.input_messages.0.message.content"] == "hi"
+    assert attrs["llm.input_messages.0.message.tool_call_id"] == "tool-1"
+    assert attrs["llm.input_messages.1.message.role"] == "assistant"
+    assert attrs["llm.input_messages.1.message.content"] == "ok"
+    assert attrs["llm.input_messages.1.message.name"] == "helper"

acty_openai-0.1.0/tests/test_openai_engine_integration.py

@@ -0,0 +1,70 @@
+import asyncio
+
+import pytest
+
+from opentelemetry import trace as otel_trace
+from opentelemetry.sdk.trace import TracerProvider as SDKTracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+from acty import ActyEngine, EngineConfig
+from acty_openai import OpenAIExecutor
+
+
+class TelemetryModel:
+    def __init__(self, cache_read: int) -> None:
+        self._cache_read = cache_read
+
+    def invoke(self, call_input, **kwargs):
+        _ = call_input
+        _ = kwargs
+        return DummyOutput(self._cache_read)
+
+
+class DummyOutput:
+    def __init__(self, cache_read: int) -> None:
+        self.llm_output = {"token_usage": {"precached_prompt_tokens": cache_read}}
+
+
+def _install_exporter() -> tuple[InMemorySpanExporter, SDKTracerProvider]:
+    exporter = InMemorySpanExporter()
+    provider = otel_trace.get_tracer_provider()
+    if not isinstance(provider, SDKTracerProvider):
+        provider = SDKTracerProvider()
+        otel_trace.set_tracer_provider(provider)
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    return exporter, provider
+
+
+@pytest.mark.asyncio
+async def test_openai_engine_emits_shared_telemetry_attributes() -> None:
+    exporter, provider = _install_exporter()
+    model = TelemetryModel(cache_read=7)
+    executor = OpenAIExecutor(model=model)
+    engine = ActyEngine(
+        executor=executor,
+        config=EngineConfig(primer_workers=1, follower_workers=1),
+    )
+    try:
+        payload = {
+            "messages": [{"role": "user", "content": "hello"}],
+            "invoke_kwargs": {"config": {"run_name": "telemetry-run"}},
+        }
+        submission = await engine.submit_group("g-telemetry", payload, [])
+        assert submission.primer is not None
+        result = await asyncio.wait_for(submission.primer, timeout=2.0)
+        assert result.ok is True
+    finally:
+        await engine.close()
+
+    provider.force_flush()
+    spans = exporter.get_finished_spans()
+    assert spans
+    job_id = str(result.job_id)
+    job_spans = [span for span in spans if span.attributes.get("acty.job_id") == job_id]
+    assert job_spans
+    attrs = job_spans[0].attributes
+    assert attrs["llm.input_messages.0.message.role"] == "user"
+    assert attrs["llm.input_messages.0.message.content"] == "hello"
+    assert attrs["llm.token_count.prompt_details.cache_read"] == 7
+    assert attrs["acty.run_name"] == "telemetry-run"