langchain-nace 0.1.0__tar.gz

langchain_nace-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.coverage
+coverage.xml
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env

langchain_nace-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nace AI
+
+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.

langchain_nace-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.5
+Name: langchain-nace
+Version: 0.1.0
+Summary: LangChain integration for Drex decision models by Nace
+Project-URL: Homepage, https://console.nace.ai/docs
+Project-URL: Repository, https://github.com/nace-ai/langchain-nace
+Project-URL: Issues, https://github.com/nace-ai/langchain-nace/issues
+Author-email: Nace AI <hello@nace.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: classifier,decision-model,drex,guardrails,langchain,langgraph,middleware,nace,router
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0,>=3.11
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: langchain-core<2.0.0,>=1.6.13
+Requires-Dist: nace-sdk<1.0.0,>=0.3.0
+Requires-Dist: pydantic<3.0.0,>=2.11
+Provides-Extra: experimental
+Requires-Dist: langchain<2.0.0,>=1.4.0; extra == 'experimental'
+Description-Content-Type: text/markdown
+
+# langchain-nace
+
+LangChain integration for [Drex](https://console.nace.ai/docs), Nace's decision models. Drex reads text, JSON, LangChain messages and (on Drex Max) images, and returns typed answers with calibrated probabilities instead of generated text. Use it to route requests, pick models, or check tool calls before they run.
+
+```bash
+pip install langchain-nace                  # classifier, router, LangGraph edge
+pip install "langchain-nace[experimental]"  # + agent middleware
+export NACE_API_KEY=nace_sk_...
+```
+
+## Quickstart
+
+```python
+from langchain_nace import Choice, NaceClassifier, Noul, Score
+
+classifier = NaceClassifier()  # model="drex-max" by default
+
+response = classifier.invoke({
+    "state": "I was charged twice for March and I'm annoyed. Please refund one.",
+    "questions": {
+        "refund": Noul(instructions="Is the customer asking for a refund?"),
+        "team": Choice(
+            instructions="Which team should handle this?",
+            criteria={"billing": "Payments and refunds", "technical": "Bugs"},
+        ),
+        "mood": Score(instructions="How upset is the customer?", criteria=["calm", "annoyed", "furious"]),
+    },
+})
+response.nouls["refund"].noul             # 0.98: probability of yes
+response.choices["team"].probabilities    # {"billing": 0.99, "technical": 0.01}
+response.scores["mood"].score             # 1.1: expected level
+```
+
+All questions about one state go in one request. Answers keep their full probabilities, so thresholds stay in your code. `ainvoke`, `batch` and `abatch` work as on any Runnable. `batch` runs at most 8 requests at once unless you set `max_concurrency`.
+
+**Switching from `langchain-typesafe`:** change the import to `from langchain_nace import ...` and `TypeSafeClassifier` to `NaceClassifier`. `Noul`, `Choice`, `Score`, `NoulCriteria` and the response fields (`nouls`, `choices`, `scores`, `usage`, `request_id`) have the same names.
+
+## Models
+
+The default is **`drex-max`**: it reads images, and takes up to 16 questions per request. For text-only work with more questions per request (up to 512), use `NaceClassifier(model="drex-v2.0")`. Any other model id is accepted and sent as given (`drex-v1.5`, `drex-latest`, and models released later); Drex enforces each model's limits, and errors tell you what to change. Pin a default for your app with `model=` or `NACE_DEFAULT_DECISION_MODEL`. The package default moves to the newest flagship with each Drex release, so pin a model if you need results that never change.
+
+## Images (Drex Max)
+
+```python
+max_ = NaceClassifier()  # drex-max
+max_.invoke({
+    "state": "Two product photos.",
+    "images": [red_png_bytes, "data:image/jpeg;base64,..."],
+    "questions": {"damaged": Choice(instructions="Which image shows damage?",
+                                    criteria={"Image 1": None, "Image 2": None})},
+})
+```
+
+Images can be bytes, paths, base64, data URLs, LangChain image blocks (`{"type": "image", "base64": ...}`, `source_type: "base64"`, `image_url`), or files uploaded with `nace_sdk` (`{"type": "workspace_file", ...}`). Images inside LangChain messages in `state` are moved to `images` automatically and referred to as "Image N". Drex doesn't fetch URLs, so remote image URLs are refused. Sending images to a text-only model (`drex-v2.0`, `drex-v1.5`) raises `NaceImageModelError` before anything is sent; images are never dropped silently.
+
+## Routing
+
+```python
+from langchain_nace import NaceRouter
+
+router = NaceRouter(classifier=classifier, question=Choice(
+    instructions="Which team?", criteria={"billing": None, "technical": None}),
+    min_confidence=0.6, fallback="human")
+chain = router.branch({"billing": billing_chain, "technical": tech_chain, "human": escalate},
+                      default=escalate)
+```
+
+LangGraph: `nace_conditional_edge(classifier, question, state=..., min_confidence=0.7)` is a path function for `add_conditional_edges`. Below the threshold it returns `"human_review"`, so that node can `interrupt()` for a person. See [`examples/langgraph_router.py`](https://github.com/nace-ai/langchain-nace/blob/main/examples/langgraph_router.py).
+
+## Agent middleware (experimental)
+
+```python
+from langchain.agents import create_agent
+from langgraph.checkpoint.memory import InMemorySaver
+from langchain_nace.experimental.middleware import (
+    ModelChoice, NaceAutoModeMiddleware, NaceModelRouterMiddleware)
+
+router = NaceModelRouterMiddleware(
+    choices={"fast": ModelChoice("openai:gpt-5-mini", "Short lookups"),
+             "strong": ModelChoice("anthropic:claude-opus-5-5", "Multi-step changes")},
+    instructions="Pick the cheapest model that can do this safely.",
+)
+gate = NaceAutoModeMiddleware(screenshots=True)  # drex-max reads the screenshots
+agent = create_agent("openai:gpt-5-mini", tools=tools, middleware=[router, gate],
+                     checkpointer=InMemorySaver())
+```
+
+**`NaceModelRouterMiddleware`** picks the model once per run. Below `min_confidence` (0.6), or if Drex can't be reached, it uses `escalate_to` (the last choice by default). The decision and probabilities are kept in state under `nace_model_route`.
+
+**`NaceAutoModeMiddleware`** checks each tool call before it runs. In one request Drex reads:
+- the user's **original request**, kept however long the run gets;
+- the latest user message and the last 20 messages;
+- the tool call and its description;
+- with `screenshots=True` and Drex Max, the newest screenshots.
+
+It answers three questions: a risk score, "destructive?" and "did the user ask for this?". The default `ThresholdPolicy` then decides:
+- **block** at risk ≥ 0.75, or when the call is destructive and the user didn't ask for it;
+- **ask a person** at risk ≥ 0.4, or when the call is destructive and the user asked for it;
+- **allow** otherwise.
+
+Asking uses a LangGraph `interrupt`. Resume it with `{"type": "approve"}`, `{"type": "reject", "message": ...}` or `{"type": "edit", "args": {...}}`. If Drex fails, the call is blocked (`on_error="block"`). Questions, thresholds and the policy are all replaceable. Write your own `GatePolicy`, or subclass `GateDecision`.
+
+[`examples/support_agent.py`](https://github.com/nace-ai/langchain-nace/blob/main/examples/support_agent.py) runs four live scenarios: an allowed read, a blocked unrequested delete, a person approving a requested delete, and a screenshot-based block on a computer-use click.
+
+## Backends
+
+| Backend | `base_url` | Notes |
+|---|---|---|
+| Nace (default) | `https://console.nace.ai` | `NACE_BASE_URL` |
+| OpenRouter | `https://openrouter.ai/api/v1` | models `nace-ai/drex-v2.0`, `nace-ai/drex-max`; images are sent the way OpenRouter expects |
+| Vercel AI Gateway / TypeSafe-compatible hosts | the host's System One root | same request format as Nace |
+
+Every request sends `User-Agent` and `X-Nace-Client: langchain-nace/<version>`. On OpenRouter it also sends `HTTP-Referer` and `X-OpenRouter-Title`.
+
+## Errors
+
+Errors also inherit LangChain's `Model*Error` classes, and messages never include your state:
+
+| Error | When |
+|---|---|
+| `NaceAuthenticationError` | 401 |
+| `NaceInsufficientCreditError` | 402, with the Billing link |
+| `NaceUnprocessableEntityError` | 422; lists each issue's `path: message` |
+| `NaceRateLimitError` | 429, after retries |
+| `NaceOverloadedError` | 529, after retries |
+| `NaceAPIConnectionError` / `NaceAPITimeoutError` | network problems |
+
+429, 529 and 5xx responses are retried (`max_retries=2`), waiting as long as `retry-after-ms` asks. The timeout is 60 s, because Drex may take up to 55 s.
+
+## Tracing
+
+Calls show up in LangSmith as `llm` runs (`ls_provider="nace"`) with the questions, the full answers and probabilities, token usage and the Drex request id. The router and middlewares add their thresholds to the run metadata.
+
+## Development
+
+```bash
+uv sync --all-extras --all-groups
+make test lint typecheck                 # offline: fake Drex server
+NACE_API_KEY_LIVE=nace_sk_... make integration_tests   # live contract tests
+```

langchain_nace-0.1.0/README.md

@@ -0,0 +1,140 @@
+# langchain-nace
+
+LangChain integration for [Drex](https://console.nace.ai/docs), Nace's decision models. Drex reads text, JSON, LangChain messages and (on Drex Max) images, and returns typed answers with calibrated probabilities instead of generated text. Use it to route requests, pick models, or check tool calls before they run.
+
+```bash
+pip install langchain-nace                  # classifier, router, LangGraph edge
+pip install "langchain-nace[experimental]"  # + agent middleware
+export NACE_API_KEY=nace_sk_...
+```
+
+## Quickstart
+
+```python
+from langchain_nace import Choice, NaceClassifier, Noul, Score
+
+classifier = NaceClassifier()  # model="drex-max" by default
+
+response = classifier.invoke({
+    "state": "I was charged twice for March and I'm annoyed. Please refund one.",
+    "questions": {
+        "refund": Noul(instructions="Is the customer asking for a refund?"),
+        "team": Choice(
+            instructions="Which team should handle this?",
+            criteria={"billing": "Payments and refunds", "technical": "Bugs"},
+        ),
+        "mood": Score(instructions="How upset is the customer?", criteria=["calm", "annoyed", "furious"]),
+    },
+})
+response.nouls["refund"].noul             # 0.98: probability of yes
+response.choices["team"].probabilities    # {"billing": 0.99, "technical": 0.01}
+response.scores["mood"].score             # 1.1: expected level
+```
+
+All questions about one state go in one request. Answers keep their full probabilities, so thresholds stay in your code. `ainvoke`, `batch` and `abatch` work as on any Runnable. `batch` runs at most 8 requests at once unless you set `max_concurrency`.
+
+**Switching from `langchain-typesafe`:** change the import to `from langchain_nace import ...` and `TypeSafeClassifier` to `NaceClassifier`. `Noul`, `Choice`, `Score`, `NoulCriteria` and the response fields (`nouls`, `choices`, `scores`, `usage`, `request_id`) have the same names.
+
+## Models
+
+The default is **`drex-max`**: it reads images, and takes up to 16 questions per request. For text-only work with more questions per request (up to 512), use `NaceClassifier(model="drex-v2.0")`. Any other model id is accepted and sent as given (`drex-v1.5`, `drex-latest`, and models released later); Drex enforces each model's limits, and errors tell you what to change. Pin a default for your app with `model=` or `NACE_DEFAULT_DECISION_MODEL`. The package default moves to the newest flagship with each Drex release, so pin a model if you need results that never change.
+
+## Images (Drex Max)
+
+```python
+max_ = NaceClassifier()  # drex-max
+max_.invoke({
+    "state": "Two product photos.",
+    "images": [red_png_bytes, "data:image/jpeg;base64,..."],
+    "questions": {"damaged": Choice(instructions="Which image shows damage?",
+                                    criteria={"Image 1": None, "Image 2": None})},
+})
+```
+
+Images can be bytes, paths, base64, data URLs, LangChain image blocks (`{"type": "image", "base64": ...}`, `source_type: "base64"`, `image_url`), or files uploaded with `nace_sdk` (`{"type": "workspace_file", ...}`). Images inside LangChain messages in `state` are moved to `images` automatically and referred to as "Image N". Drex doesn't fetch URLs, so remote image URLs are refused. Sending images to a text-only model (`drex-v2.0`, `drex-v1.5`) raises `NaceImageModelError` before anything is sent; images are never dropped silently.
+
+## Routing
+
+```python
+from langchain_nace import NaceRouter
+
+router = NaceRouter(classifier=classifier, question=Choice(
+    instructions="Which team?", criteria={"billing": None, "technical": None}),
+    min_confidence=0.6, fallback="human")
+chain = router.branch({"billing": billing_chain, "technical": tech_chain, "human": escalate},
+                      default=escalate)
+```
+
+LangGraph: `nace_conditional_edge(classifier, question, state=..., min_confidence=0.7)` is a path function for `add_conditional_edges`. Below the threshold it returns `"human_review"`, so that node can `interrupt()` for a person. See [`examples/langgraph_router.py`](https://github.com/nace-ai/langchain-nace/blob/main/examples/langgraph_router.py).
+
+## Agent middleware (experimental)
+
+```python
+from langchain.agents import create_agent
+from langgraph.checkpoint.memory import InMemorySaver
+from langchain_nace.experimental.middleware import (
+    ModelChoice, NaceAutoModeMiddleware, NaceModelRouterMiddleware)
+
+router = NaceModelRouterMiddleware(
+    choices={"fast": ModelChoice("openai:gpt-5-mini", "Short lookups"),
+             "strong": ModelChoice("anthropic:claude-opus-5-5", "Multi-step changes")},
+    instructions="Pick the cheapest model that can do this safely.",
+)
+gate = NaceAutoModeMiddleware(screenshots=True)  # drex-max reads the screenshots
+agent = create_agent("openai:gpt-5-mini", tools=tools, middleware=[router, gate],
+                     checkpointer=InMemorySaver())
+```
+
+**`NaceModelRouterMiddleware`** picks the model once per run. Below `min_confidence` (0.6), or if Drex can't be reached, it uses `escalate_to` (the last choice by default). The decision and probabilities are kept in state under `nace_model_route`.
+
+**`NaceAutoModeMiddleware`** checks each tool call before it runs. In one request Drex reads:
+- the user's **original request**, kept however long the run gets;
+- the latest user message and the last 20 messages;
+- the tool call and its description;
+- with `screenshots=True` and Drex Max, the newest screenshots.
+
+It answers three questions: a risk score, "destructive?" and "did the user ask for this?". The default `ThresholdPolicy` then decides:
+- **block** at risk ≥ 0.75, or when the call is destructive and the user didn't ask for it;
+- **ask a person** at risk ≥ 0.4, or when the call is destructive and the user asked for it;
+- **allow** otherwise.
+
+Asking uses a LangGraph `interrupt`. Resume it with `{"type": "approve"}`, `{"type": "reject", "message": ...}` or `{"type": "edit", "args": {...}}`. If Drex fails, the call is blocked (`on_error="block"`). Questions, thresholds and the policy are all replaceable. Write your own `GatePolicy`, or subclass `GateDecision`.
+
+[`examples/support_agent.py`](https://github.com/nace-ai/langchain-nace/blob/main/examples/support_agent.py) runs four live scenarios: an allowed read, a blocked unrequested delete, a person approving a requested delete, and a screenshot-based block on a computer-use click.
+
+## Backends
+
+| Backend | `base_url` | Notes |
+|---|---|---|
+| Nace (default) | `https://console.nace.ai` | `NACE_BASE_URL` |
+| OpenRouter | `https://openrouter.ai/api/v1` | models `nace-ai/drex-v2.0`, `nace-ai/drex-max`; images are sent the way OpenRouter expects |
+| Vercel AI Gateway / TypeSafe-compatible hosts | the host's System One root | same request format as Nace |
+
+Every request sends `User-Agent` and `X-Nace-Client: langchain-nace/<version>`. On OpenRouter it also sends `HTTP-Referer` and `X-OpenRouter-Title`.
+
+## Errors
+
+Errors also inherit LangChain's `Model*Error` classes, and messages never include your state:
+
+| Error | When |
+|---|---|
+| `NaceAuthenticationError` | 401 |
+| `NaceInsufficientCreditError` | 402, with the Billing link |
+| `NaceUnprocessableEntityError` | 422; lists each issue's `path: message` |
+| `NaceRateLimitError` | 429, after retries |
+| `NaceOverloadedError` | 529, after retries |
+| `NaceAPIConnectionError` / `NaceAPITimeoutError` | network problems |
+
+429, 529 and 5xx responses are retried (`max_retries=2`), waiting as long as `retry-after-ms` asks. The timeout is 60 s, because Drex may take up to 55 s.
+
+## Tracing
+
+Calls show up in LangSmith as `llm` runs (`ls_provider="nace"`) with the questions, the full answers and probabilities, token usage and the Drex request id. The router and middlewares add their thresholds to the run metadata.
+
+## Development
+
+```bash
+uv sync --all-extras --all-groups
+make test lint typecheck                 # offline: fake Drex server
+NACE_API_KEY_LIVE=nace_sk_... make integration_tests   # live contract tests
+```

langchain_nace-0.1.0/langchain_nace/__init__.py

@@ -0,0 +1,81 @@
+"""LangChain integration for Drex decision models by Nace."""
+
+from langchain_nace._version import __version__
+from langchain_nace.classifier import NaceClassifier
+from langchain_nace.errors import (
+    NaceAPIConnectionError,
+    NaceAPIError,
+    NaceAPIResponseValidationError,
+    NaceAPITimeoutError,
+    NaceAuthenticationError,
+    NaceBadRequestError,
+    NaceError,
+    NaceImageError,
+    NaceImageModelError,
+    NaceInsufficientCreditError,
+    NaceInternalServerError,
+    NaceMediaError,
+    NaceNotFoundError,
+    NaceOverloadedError,
+    NacePermissionDeniedError,
+    NaceRateLimitError,
+    NaceUnprocessableEntityError,
+)
+from langchain_nace.graph import nace_conditional_edge
+from langchain_nace.router import NaceLowConfidenceError, NaceRouter, RouteDecision
+from langchain_nace.types import (
+    Answer,
+    Choice,
+    ChoiceAnswer,
+    ClassifierRequest,
+    ClassifierResponse,
+    Noul,
+    NoulAnswer,
+    NoulCriteria,
+    Question,
+    RawAnswer,
+    Score,
+    ScoreAnswer,
+    State,
+    Usage,
+)
+
+__all__ = [
+    "Answer",
+    "Choice",
+    "ChoiceAnswer",
+    "ClassifierRequest",
+    "ClassifierResponse",
+    "NaceAPIConnectionError",
+    "NaceAPIError",
+    "NaceAPIResponseValidationError",
+    "NaceAPITimeoutError",
+    "NaceAuthenticationError",
+    "NaceBadRequestError",
+    "NaceClassifier",
+    "NaceError",
+    "NaceImageError",
+    "NaceImageModelError",
+    "NaceInsufficientCreditError",
+    "NaceInternalServerError",
+    "NaceLowConfidenceError",
+    "NaceMediaError",
+    "NaceNotFoundError",
+    "NaceOverloadedError",
+    "NacePermissionDeniedError",
+    "NaceRateLimitError",
+    "NaceRouter",
+    "NaceUnprocessableEntityError",
+    "Noul",
+    "NoulAnswer",
+    "NoulCriteria",
+    "Question",
+    "RawAnswer",
+    "RouteDecision",
+    "Score",
+    "ScoreAnswer",
+    "State",
+    "Usage",
+    "__version__",
+    "nace_conditional_edge",
+]

langchain_nace-0.1.0/langchain_nace/_images.py

@@ -0,0 +1,124 @@
+"""Convert images to the entries Drex reads in a request's `images` array."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+from collections.abc import Mapping
+from typing import Any
+
+import nace_sdk
+
+from langchain_nace.errors import NaceImageError
+
+_REMOTE = ("http://", "https://")
+
+
+def _remote_url_error(url: str) -> NaceImageError:
+    return NaceImageError(
+        f"Drex doesn't fetch image URLs ({url[:60]}…). Download the image and pass its "
+        "bytes, or upload it with `nace_sdk` and pass the uploaded file."
+    )
+
+
+def _from_url(url: str) -> str:
+    if url.startswith("data:"):
+        return url
+    if url.startswith(_REMOTE):
+        raise _remote_url_error(url)
+    return url
+
+
+def _from_base64(data: str, mime_type: str | None) -> str:
+    return f"data:{mime_type};base64,{data}" if mime_type else data
+
+
+_SIGNATURES = (
+    (b"\x89PNG\r\n\x1a\n", "image/png"),
+    (b"\xff\xd8\xff", "image/jpeg"),
+    (b"GIF8", "image/gif"),
+)
+
+
+def as_data_url(image: str) -> str:
+    """A data URL for base64 image bytes, typed from their first bytes."""
+    if image.startswith("data:"):
+        return image
+    head = base64.b64decode(image[:24] + "=" * (-len(image[:24]) % 4), validate=False)
+    mime = next((m for sig, m in _SIGNATURES if head.startswith(sig)), None)
+    if mime is None and head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        mime = "image/webp"
+    return f"data:{mime or 'application/octet-stream'};base64,{image}"
+
+
+def _is_base64(value: str) -> bool:
+    if len(value) % 4:
+        return False
+    try:
+        base64.b64decode(value, validate=True)
+    except (binascii.Error, ValueError):
+        return False
+    return True
+
+
+def to_drex_image(item: Any) -> str | dict[str, Any]:
+    """Return one `images` entry for Drex.
+
+    Accepts base64, a data URL, bytes, a path, a LangChain image content block (v0
+    `source_type`, v1 `base64`/`url`), an `image_url` block, a `workspace_file`
+    reference, or an `UploadedFile`. Remote URLs are refused: Drex never fetches them.
+
+    Raises:
+        NaceImageError: The item isn't an image Drex can read.
+
+    """
+    if isinstance(item, str):
+        if item.startswith(("data:", *_REMOTE)):
+            return _from_url(item)
+        if _is_base64(item):
+            return item
+        if os.path.exists(item):
+            return _from_sdk(item)
+        message = f"{item[:60]!r} is not base64, a data URL, or an existing file path."
+        raise NaceImageError(message)
+    if isinstance(item, bytes | bytearray | os.PathLike):
+        return _from_sdk(item)
+    if isinstance(item, nace_sdk.UploadedFile | nace_sdk.WorkspaceFileSource):
+        return _from_sdk(item)
+    if isinstance(item, Mapping):
+        return _from_block(item)
+    message = f"Unsupported image type: {type(item).__name__}."
+    raise NaceImageError(message)
+
+
+def _from_sdk(item: Any) -> str | dict[str, Any]:
+    try:
+        return nace_sdk.image_input(item)
+    except nace_sdk.NaceError as error:
+        raise NaceImageError(str(error)) from error
+
+
+def _from_block(block: Mapping[str, Any]) -> str | dict[str, Any]:
+    kind = block.get("type")
+    if kind == "workspace_file":
+        return dict(block)
+    if kind == "image_url":
+        image_url = block.get("image_url")
+        url = image_url.get("url") if isinstance(image_url, Mapping) else image_url
+        if isinstance(url, str):
+            return _from_url(url)
+    if kind == "image":
+        mime_type = block.get("mime_type")
+        if block.get("source_type") == "base64" and isinstance(block.get("data"), str):
+            return _from_base64(block["data"], mime_type)
+        if isinstance(block.get("base64"), str):
+            return _from_base64(block["base64"], mime_type)
+        url = block.get("url") or (block.get("data") if block.get("source_type") == "url" else None)
+        if isinstance(url, str):
+            return _from_url(url)
+    message = f"Unsupported image block: {dict(block)!r:.80}"
+    raise NaceImageError(message)
+
+
+__all__ = ["as_data_url", "to_drex_image"]

langchain_nace-0.1.0/langchain_nace/_state.py

@@ -0,0 +1,119 @@
+"""Turn state containing LangChain messages into the JSON Drex reads.
+
+Drex rejects media inside `state`. Images found in messages are either moved to the
+request's `images` array (replaced in the text by "[Image N]"), replaced by a
+placeholder, or refused, depending on the caller. Other media (audio, files) is
+replaced by a placeholder or refused.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from langchain_core.messages import BaseMessage, convert_to_openai_messages
+
+from langchain_nace._images import to_drex_image
+from langchain_nace.errors import NaceImageModelError, NaceMediaError
+
+ImageMode = Literal["lift", "placeholder", "error"]
+MediaMode = Literal["placeholder", "error"]
+
+
+@dataclass
+class _Encoder:
+    images: ImageMode
+    media: MediaMode
+    first_index: int
+    lifted: list[str | dict[str, Any]] = field(default_factory=list)
+
+    def value(self, value: Any) -> Any:
+        if isinstance(value, BaseMessage):
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore")
+                converted = convert_to_openai_messages(value)
+            return self.message(converted)
+        if isinstance(value, dict):
+            if not all(isinstance(key, str) for key in value):
+                message = "State object keys must be strings."
+                raise TypeError(message)
+            return {key: self.value(item) for key, item in value.items()}
+        if isinstance(value, Sequence) and not isinstance(value, str | bytes | bytearray):
+            return [self.value(item) for item in value]
+        if value is None or isinstance(value, str | int | float | bool):
+            return value
+        message = f"Unsupported state value: {type(value).__name__}."
+        raise TypeError(message)
+
+    def message(self, message: dict[str, Any]) -> dict[str, Any]:
+        content = message.get("content")
+        if isinstance(content, list):
+            message = {**message, "content": [self.part(part) for part in content]}
+        return message
+
+    def part(self, part: Any) -> Any:
+        if not isinstance(part, dict):
+            return part
+        kind = part.get("type")
+        if kind == "text":
+            return part
+        if kind == "image_url":
+            return self.image(part)
+        if self.media == "error":
+            message = (
+                f"Drex reads text and images only; the state holds a `{kind}` content block. "
+                "Remove it, or describe it in text."
+            )
+            raise NaceMediaError(message)
+        return {"type": "text", "text": f"[{kind or 'content'} omitted]"}
+
+    def image(self, part: dict[str, Any]) -> dict[str, Any]:
+        if self.images == "placeholder":
+            return {"type": "text", "text": "[image omitted]"}
+        if self.images == "error":
+            message = (
+                "The state holds an image, but this model reads text only. "
+                "Use an image model such as model='drex-max'."
+            )
+            raise NaceImageModelError(message)
+        self.lifted.append(to_drex_image(part))
+        return {"type": "text", "text": f"[Image {self.first_index + len(self.lifted) - 1}]"}
+
+
+def encode_state(
+    state: Any,
+    *,
+    images: ImageMode,
+    media: MediaMode = "error",
+    first_index: int = 1,
+) -> tuple[Any, list[str | dict[str, Any]]]:
+    """Return `(state_json, lifted_images)`.
+
+    Args:
+        state: A string, JSON object or array, a message, or messages at any depth.
+        images: What to do with images in messages: move them to `images` ("lift"),
+            replace them with "[image omitted]", or raise.
+        media: What to do with audio, files and other media: replace or raise.
+        first_index: Number of the first lifted image, after any explicit images.
+
+    Raises:
+        TypeError: The root is a bare number, boolean or `None`, or a value isn't JSON.
+        NaceImageModelError: An image was found and `images="error"`.
+        NaceMediaError: Other media was found and `media="error"`.
+
+    """
+    if state is None or isinstance(state, bool | int | float):
+        message = "State must be a string, a JSON object or array, or LangChain messages."
+        raise TypeError(message)
+    encoder = _Encoder(images=images, media=media, first_index=first_index)
+    return encoder.value(state), encoder.lifted
+
+
+def message_text(message: BaseMessage) -> str:
+    """The text of a message, with non-text blocks left out."""
+    return message.text if isinstance(message.text, str) else str(message.text)
+
+
+__all__ = ["encode_state", "message_text"]

langchain_nace-0.1.0/langchain_nace/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.1.0"