langchain-idemcore 0.1.0__tar.gz

langchain_idemcore-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: langchain-idemcore
+Version: 0.1.0
+Summary: LangChain chat model for Idemcore, with signed verifiable receipts in response metadata.
+Author-email: Don Wick <don.wick@idemcore.net>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://idemcore.net
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: idemcore<0.4,>=0.3.0
+Requires-Dist: idemcore-verify<0.4,>=0.3.6
+Requires-Dist: langchain-core>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+
+# langchain-idemcore
+
+LangChain chat model for the [Idemcore](https://idemcore.net) API. Every answer
+comes with a signed, independently verifiable, bit-exact receipt, stored on
+`AIMessage.response_metadata`.
+
+Private package. Do not publish to PyPI without explicit approval.
+
+## Install (local)
+
+```bash
+pip install -e /workspace/idemcore-integrations/packages/langchain-idemcore
+export IDEMCORE_API_KEY=ick_...
+```
+
+Requires `idemcore>=0.3` (r2 receipts) and `idemcore-verify>=0.3.6`.
+
+## Quickstart
+
+```python
+from langchain_core.messages import HumanMessage
+from langchain_idemcore import ChatIdemcore, IdemcoreReceiptHandler, verify_langchain_receipt
+
+llm = ChatIdemcore(model="your-model-id", max_tokens=64)
+handler = IdemcoreReceiptHandler()
+
+msg = llm.invoke(
+    [HumanMessage(content="Name the three primary colours.")],
+    config={"callbacks": [handler]},
+)
+print(msg.content)
+print(msg.response_metadata["receipt_id"])   # rcpt_...
+print(handler.to_jsonl())
+
+# Local check of the signed receipt (and of a public token log, if you have one):
+# bundle = verify_langchain_receipt(msg, log_text=log_text)
+# print(bundle.ok, bundle.verification.levels)
+```
+
+Streaming works the same way: text arrives in chunks, and the receipt is
+attached to a later chunk's `response_metadata` once the answer is complete.
+Merging the `AIMessageChunk`s (or using `IdemcoreReceiptHandler`) preserves it.
+
+```python
+for chunk in llm.stream([HumanMessage(content="Write one short sentence.")]):
+    print(chunk.content, end="")
+```
+
+## Receipt metadata
+
+`AIMessage.response_metadata` (and `ChatResult.llm_output`) contains:
+
+- `receipt_id`, `receipt` (the full signed r2 receipt)
+- `salt` (for `hash_only` receipts; store it with the conversation)
+- `privacy`, `model`, `finish_reason`, `id`, `usage`
+
+`IdemcoreReceiptHandler` collects those payloads for a whole run and can write
+them as JSONL.
+
+`verify_langchain_receipt` runs `idemcore.verify_receipt` (signature, optional
+token-log chain, optional prompt/answer commitments). When `log_text` is
+given it also runs the open `idemcore-verify` log check.
+
+## Sampling
+
+Idemcore decoding is greedy: **temperature is fixed at 0**. Passing any other
+temperature, or sampling settings such as `top_p`, `top_k`, penalties, `seed`,
+`n`, or stop sequences, raises an error before a request is made. Tool and
+function calling are not supported.
+
+`max_tokens` must be a whole number from 1 to 2048. `privacy` is `hash_only`
+(default) or `full`. Auth is `IDEMCORE_API_KEY` (or `api_key=`). Billing is
+measured server-side in tokens.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Unit tests mock the SDK. A live smoke test runs only when `IDEMCORE_API_KEY`
+is set in the environment.

langchain_idemcore-0.1.0/README.md

@@ -0,0 +1,83 @@
+# langchain-idemcore
+
+LangChain chat model for the [Idemcore](https://idemcore.net) API. Every answer
+comes with a signed, independently verifiable, bit-exact receipt, stored on
+`AIMessage.response_metadata`.
+
+Private package. Do not publish to PyPI without explicit approval.
+
+## Install (local)
+
+```bash
+pip install -e /workspace/idemcore-integrations/packages/langchain-idemcore
+export IDEMCORE_API_KEY=ick_...
+```
+
+Requires `idemcore>=0.3` (r2 receipts) and `idemcore-verify>=0.3.6`.
+
+## Quickstart
+
+```python
+from langchain_core.messages import HumanMessage
+from langchain_idemcore import ChatIdemcore, IdemcoreReceiptHandler, verify_langchain_receipt
+
+llm = ChatIdemcore(model="your-model-id", max_tokens=64)
+handler = IdemcoreReceiptHandler()
+
+msg = llm.invoke(
+    [HumanMessage(content="Name the three primary colours.")],
+    config={"callbacks": [handler]},
+)
+print(msg.content)
+print(msg.response_metadata["receipt_id"])   # rcpt_...
+print(handler.to_jsonl())
+
+# Local check of the signed receipt (and of a public token log, if you have one):
+# bundle = verify_langchain_receipt(msg, log_text=log_text)
+# print(bundle.ok, bundle.verification.levels)
+```
+
+Streaming works the same way: text arrives in chunks, and the receipt is
+attached to a later chunk's `response_metadata` once the answer is complete.
+Merging the `AIMessageChunk`s (or using `IdemcoreReceiptHandler`) preserves it.
+
+```python
+for chunk in llm.stream([HumanMessage(content="Write one short sentence.")]):
+    print(chunk.content, end="")
+```
+
+## Receipt metadata
+
+`AIMessage.response_metadata` (and `ChatResult.llm_output`) contains:
+
+- `receipt_id`, `receipt` (the full signed r2 receipt)
+- `salt` (for `hash_only` receipts; store it with the conversation)
+- `privacy`, `model`, `finish_reason`, `id`, `usage`
+
+`IdemcoreReceiptHandler` collects those payloads for a whole run and can write
+them as JSONL.
+
+`verify_langchain_receipt` runs `idemcore.verify_receipt` (signature, optional
+token-log chain, optional prompt/answer commitments). When `log_text` is
+given it also runs the open `idemcore-verify` log check.
+
+## Sampling
+
+Idemcore decoding is greedy: **temperature is fixed at 0**. Passing any other
+temperature, or sampling settings such as `top_p`, `top_k`, penalties, `seed`,
+`n`, or stop sequences, raises an error before a request is made. Tool and
+function calling are not supported.
+
+`max_tokens` must be a whole number from 1 to 2048. `privacy` is `hash_only`
+(default) or `full`. Auth is `IDEMCORE_API_KEY` (or `api_key=`). Billing is
+measured server-side in tokens.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Unit tests mock the SDK. A live smoke test runs only when `IDEMCORE_API_KEY`
+is set in the environment.

langchain_idemcore-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langchain-idemcore"
+version = "0.1.0"
+description = "LangChain chat model for Idemcore, with signed verifiable receipts in response metadata."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "Apache-2.0"
+authors = [{ name = "Don Wick", email = "don.wick@idemcore.net" }]
+dependencies = [
+  "idemcore>=0.3.0,<0.4",
+  "idemcore-verify>=0.3.6,<0.4",
+  "langchain-core>=0.3.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[project.urls]
+Homepage = "https://idemcore.net"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+pythonpath = ["src", "."]

langchain_idemcore-0.1.0/setup.cfg

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

langchain_idemcore-0.1.0/src/langchain_idemcore/__init__.py

@@ -0,0 +1,13 @@
+"""LangChain integration for the Idemcore API."""
+from .callback import IdemcoreReceiptHandler
+from .chat_models import ChatIdemcore
+from .verify import VerificationBundle, verify_langchain_receipt
+
+__version__ = "0.1.0"
+__all__ = [
+    "ChatIdemcore",
+    "IdemcoreReceiptHandler",
+    "VerificationBundle",
+    "verify_langchain_receipt",
+    "__version__",
+]

langchain_idemcore-0.1.0/src/langchain_idemcore/_convert.py

@@ -0,0 +1,79 @@
+"""Convert LangChain messages to the Idemcore chat message list."""
+from __future__ import annotations
+
+from typing import Any, List, Sequence
+
+from langchain_core.messages import (
+    AIMessage,
+    BaseMessage,
+    HumanMessage,
+    SystemMessage,
+)
+
+
+class UnsupportedMessageError(ValueError):
+    """Raised when a message cannot be sent to the Idemcore chat API."""
+
+
+def _content_to_text(content: Any) -> str:
+    if content is None:
+        return ""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: List[str] = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict):
+                btype = block.get("type")
+                if btype in (None, "text") and "text" in block:
+                    parts.append(str(block["text"]))
+                elif btype in ("image", "image_url", "file", "audio", "video", "media"):
+                    raise UnsupportedMessageError(
+                        "Idemcore chat accepts text messages only; multimodal content is not supported."
+                    )
+                else:
+                    raise UnsupportedMessageError(
+                        f"Unsupported LangChain content block type: {btype!r}."
+                    )
+            else:
+                text = getattr(block, "text", None)
+                if isinstance(text, str):
+                    parts.append(text)
+                else:
+                    raise UnsupportedMessageError(
+                        "Idemcore chat accepts text messages only."
+                    )
+        return "".join(parts)
+    return str(content)
+
+
+def messages_to_idemcore(messages: Sequence[BaseMessage]) -> List[dict]:
+    """Map LangChain messages to ``[{role, content}, ...]``.
+
+    Only ``system``, ``user``, and ``assistant`` text messages are accepted,
+    matching the public Idemcore SDK.
+    """
+    out: List[dict] = []
+    for msg in messages:
+        typ = getattr(msg, "type", None)
+        if isinstance(msg, SystemMessage) or typ == "system":
+            role = "system"
+        elif isinstance(msg, HumanMessage) or typ == "human":
+            role = "user"
+        elif isinstance(msg, AIMessage) or typ == "ai":
+            role = "assistant"
+        else:
+            raise UnsupportedMessageError(
+                f"Idemcore chat does not accept {type(msg).__name__} messages "
+                "(tool/function/multimodal roles are not supported)."
+            )
+        if getattr(msg, "tool_calls", None):
+            raise UnsupportedMessageError(
+                "Idemcore chat does not support tool calls."
+            )
+        out.append({"role": role, "content": _content_to_text(msg.content)})
+    if not (1 <= len(out) <= 64):
+        raise ValueError("Idemcore chat requires between 1 and 64 messages.")
+    return out

langchain_idemcore-0.1.0/src/langchain_idemcore/_receipt.py

@@ -0,0 +1,72 @@
+"""Build a JSON-serializable receipt payload from an Idemcore ChatResult."""
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from idemcore import ChatResult
+
+
+def receipt_payload(result: ChatResult) -> Dict[str, Any]:
+    """Fields stored on LangChain ``response_metadata`` / ``llm_output``."""
+    usage = dict(result.usage) if result.usage else {}
+    return {
+        "receipt_id": result.receipt_id,
+        "receipt": result.receipt,
+        "salt": result.salt,
+        "privacy": result.privacy,
+        "model": result.model,
+        "finish_reason": result.finish_reason,
+        "id": result.id,
+        "usage": usage,
+    }
+
+
+def extract_receipt_payload(source: Any) -> Optional[Dict[str, Any]]:
+    """Pull a receipt payload out of a LangChain or Idemcore object."""
+    if source is None:
+        return None
+    if isinstance(source, ChatResult):
+        return receipt_payload(source)
+    if isinstance(source, Mapping):
+        if "receipt" in source and "receipt_id" in source:
+            return dict(source)
+        if "receipt_id" in source and "receipt_version" in source:
+            return {"receipt_id": source["receipt_id"], "receipt": dict(source)}
+        meta = source.get("response_metadata") or source.get("llm_output") or source.get("idemcore")
+        if meta:
+            return extract_receipt_payload(meta)
+        inner = source.get("receipt")
+        if isinstance(inner, Mapping):
+            return {
+                "receipt_id": source.get("receipt_id") or inner.get("receipt_id"),
+                "receipt": dict(inner),
+                "salt": source.get("salt"),
+                "privacy": source.get("privacy") or inner.get("privacy"),
+                "model": source.get("model") or inner.get("model_id"),
+                "finish_reason": source.get("finish_reason"),
+                "id": source.get("id"),
+                "usage": source.get("usage") or {},
+            }
+        return None
+    meta = getattr(source, "response_metadata", None)
+    if meta:
+        found = extract_receipt_payload(meta)
+        if found:
+            return found
+    llm_output = getattr(source, "llm_output", None)
+    if llm_output:
+        found = extract_receipt_payload(llm_output)
+        if found:
+            return found
+    generations = getattr(source, "generations", None)
+    if generations:
+        first = generations[0]
+        # ChatResult.generations is list[ChatGeneration] or list[list[...]]
+        candidate = first[0] if isinstance(first, list) and first else first
+        message = getattr(candidate, "message", None)
+        if message is not None:
+            return extract_receipt_payload(message)
+        info = getattr(candidate, "generation_info", None)
+        if info:
+            return extract_receipt_payload(info)
+    return None

langchain_idemcore-0.1.0/src/langchain_idemcore/callback.py

@@ -0,0 +1,67 @@
+"""Collect signed receipts produced during a LangChain run."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+from uuid import UUID
+
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.outputs import LLMResult
+
+from ._receipt import extract_receipt_payload
+
+
+class IdemcoreReceiptHandler(BaseCallbackHandler):
+    """Callback that records every Idemcore receipt attached to an LLM result.
+
+    Use ``receipts`` / ``to_list()`` for in-memory access, or ``to_jsonl()`` /
+    ``dump_jsonl(path)`` to persist one JSON object per receipt.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.receipts: List[Dict[str, Any]] = []
+
+    def on_llm_end(
+        self,
+        response: LLMResult,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        payload = extract_receipt_payload(response)
+        if payload is None:
+            # Fall back to scanning each generation in case only some are Idemcore.
+            for group in response.generations or []:
+                items = group if isinstance(group, list) else [group]
+                for gen in items:
+                    found = extract_receipt_payload(gen) or extract_receipt_payload(
+                        getattr(gen, "message", None)
+                    )
+                    if found:
+                        payload = found
+                        break
+                if payload:
+                    break
+        if payload is not None:
+            record = dict(payload)
+            record["run_id"] = str(run_id)
+            if parent_run_id is not None:
+                record["parent_run_id"] = str(parent_run_id)
+            self.receipts.append(record)
+
+    def to_list(self) -> List[Dict[str, Any]]:
+        return list(self.receipts)
+
+    def to_jsonl(self) -> str:
+        if not self.receipts:
+            return ""
+        return "\n".join(json.dumps(r, ensure_ascii=False, default=str) for r in self.receipts) + "\n"
+
+    def dump_jsonl(self, path: Union[str, Path]) -> None:
+        Path(path).write_text(self.to_jsonl(), encoding="utf-8")
+
+    def clear(self) -> None:
+        self.receipts.clear()

langchain_idemcore-0.1.0/src/langchain_idemcore/chat_models.py

@@ -0,0 +1,269 @@
+"""LangChain chat model backed by the public Idemcore Python SDK."""
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, Iterator, List, Optional, Sequence
+
+from idemcore import AsyncIdemcore, ChatResult, Idemcore, InvalidRequestError
+from langchain_core.callbacks import AsyncCallbackManagerForLLMRun, CallbackManagerForLLMRun
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import AIMessage, AIMessageChunk, BaseMessage, UsageMetadata
+from langchain_core.outputs import ChatGeneration, ChatGenerationChunk, ChatResult as LCChatResult
+from pydantic import Field, PrivateAttr
+
+from ._convert import messages_to_idemcore
+from ._receipt import receipt_payload
+
+# Sampling keys the public SDK does not accept. A value of 0 or 1 that means
+# "off / default" is ignored; any other value is rejected.
+_BLOCKED_SAMPLING = {
+    "top_p": lambda v: v is not None and v != 1,
+    "topP": lambda v: v is not None and v != 1,
+    "top_k": lambda v: v is not None,
+    "topK": lambda v: v is not None,
+    "presence_penalty": lambda v: v not in (None, 0, 0.0),
+    "presencePenalty": lambda v: v not in (None, 0, 0.0),
+    "frequency_penalty": lambda v: v not in (None, 0, 0.0),
+    "frequencyPenalty": lambda v: v not in (None, 0, 0.0),
+    "seed": lambda v: v is not None,
+    "n": lambda v: v is not None and v != 1,
+}
+
+
+def _usage_metadata(result: ChatResult) -> Optional[UsageMetadata]:
+    usage = result.usage or {}
+    if not usage:
+        return None
+    return UsageMetadata(
+        input_tokens=int(usage.get("prompt_tokens") or 0),
+        output_tokens=int(usage.get("completion_tokens") or 0),
+        total_tokens=int(usage.get("total_tokens") or 0),
+    )
+
+
+def _ai_message(result: ChatResult) -> AIMessage:
+    payload = receipt_payload(result)
+    return AIMessage(
+        content=result.text,
+        id=result.id or None,
+        usage_metadata=_usage_metadata(result),
+        response_metadata=payload,
+        additional_kwargs={"idemcore": payload},
+    )
+
+
+class ChatIdemcore(BaseChatModel):
+    """LangChain chat model that calls Idemcore and attaches a signed receipt.
+
+    Decoding is greedy: ``temperature`` must be omitted or 0, matching the
+    public SDK. The signed receipt is stored on ``AIMessage.response_metadata``.
+    """
+
+    model: Optional[str] = Field(
+        default=None,
+        description="Idemcore model id. If omitted, the API default is used.",
+    )
+    api_key: Optional[str] = Field(
+        default=None,
+        description="API key. Defaults to the IDEMCORE_API_KEY environment variable.",
+    )
+    base_url: Optional[str] = Field(
+        default=None,
+        description="API base URL. Defaults to IDEMCORE_BASE_URL or https://api.idemcore.net.",
+    )
+    max_tokens: Optional[int] = Field(
+        default=None,
+        description="Maximum completion tokens (1–2048, per the public SDK).",
+    )
+    privacy: Optional[str] = Field(
+        default=None,
+        description="Receipt privacy: 'hash_only' (default) or 'full'.",
+    )
+    timeout: float = Field(default=120.0, description="Request timeout in seconds.")
+    temperature: Optional[float] = Field(
+        default=None,
+        description="Must be omitted or 0. Idemcore decoding is greedy.",
+    )
+
+    _sync_client: Optional[Idemcore] = PrivateAttr(default=None)
+    _async_client: Optional[AsyncIdemcore] = PrivateAttr(default=None)
+
+    @property
+    def _llm_type(self) -> str:
+        return "idemcore"
+
+    @property
+    def _identifying_params(self) -> Dict[str, Any]:
+        return {
+            "model": self.model,
+            "max_tokens": self.max_tokens,
+            "privacy": self.privacy,
+            "base_url": self.base_url,
+        }
+
+    def bind_tools(self, tools: Sequence[Any], **kwargs: Any) -> Any:
+        raise NotImplementedError(
+            "Idemcore chat does not support tool calling; bind_tools is unavailable."
+        )
+
+    def _get_sync(self) -> Idemcore:
+        if self._sync_client is None:
+            self._sync_client = Idemcore(
+                api_key=self.api_key, base_url=self.base_url, timeout=self.timeout
+            )
+        return self._sync_client
+
+    def _get_async(self) -> AsyncIdemcore:
+        if self._async_client is None:
+            self._async_client = AsyncIdemcore(
+                api_key=self.api_key, base_url=self.base_url, timeout=self.timeout
+            )
+        return self._async_client
+
+    def _chat_kwargs(self, **kwargs: Any) -> Dict[str, Any]:
+        stop = kwargs.pop("stop", None)
+        if stop:
+            raise InvalidRequestError(
+                "Idemcore does not support stop sequences; they would not be "
+                "reflected in the signed receipt.",
+                type="invalid_request_error",
+            )
+        temperature = kwargs.pop("temperature", self.temperature)
+        if temperature not in (None, 0, 0.0):
+            raise InvalidRequestError(
+                "Idemcore uses greedy decoding: temperature is fixed at 0.",
+                type="invalid_request_error",
+            )
+        for key, is_blocked in _BLOCKED_SAMPLING.items():
+            if key in kwargs and is_blocked(kwargs[key]):
+                raise InvalidRequestError(
+                    f"Idemcore does not accept the sampling parameter {key!r}. "
+                    "Decoding is greedy and temperature is fixed at 0.",
+                    type="invalid_request_error",
+                )
+            kwargs.pop(key, None)
+        # Anything else is not a public SDK chat argument.
+        for leftover in ("tools", "tool_choice", "toolChoice", "functions", "function_call"):
+            if kwargs.get(leftover):
+                raise InvalidRequestError(
+                    "Idemcore chat does not support tool or function calling.",
+                    type="invalid_request_error",
+                )
+            kwargs.pop(leftover, None)
+        model = kwargs.pop("model", self.model)
+        max_tokens = kwargs.pop("max_tokens", None)
+        if max_tokens is None:
+            max_tokens = kwargs.pop("max_output_tokens", None)
+        if max_tokens is None:
+            max_tokens = kwargs.pop("maxOutputTokens", self.max_tokens)
+        privacy = kwargs.pop("privacy", self.privacy)
+        if kwargs:
+            unexpected = ", ".join(sorted(kwargs))
+            raise InvalidRequestError(
+                f"Unsupported Idemcore chat argument(s): {unexpected}.",
+                type="invalid_request_error",
+            )
+        out: Dict[str, Any] = {}
+        if model is not None:
+            out["model"] = model
+        if max_tokens is not None:
+            out["max_tokens"] = max_tokens
+        if privacy is not None:
+            out["privacy"] = privacy
+        if temperature is not None:
+            out["temperature"] = temperature
+        return out
+
+    def _generate(
+        self,
+        messages: List[BaseMessage],
+        stop: Optional[List[str]] = None,
+        run_manager: Optional[CallbackManagerForLLMRun] = None,
+        **kwargs: Any,
+    ) -> LCChatResult:
+        kw = self._chat_kwargs(stop=stop, **kwargs)
+        result = self._get_sync().chat(messages_to_idemcore(messages), **kw)
+        message = _ai_message(result)
+        payload = receipt_payload(result)
+        return LCChatResult(
+            generations=[ChatGeneration(message=message, generation_info=payload, text=result.text)],
+            llm_output=payload,
+        )
+
+    async def _agenerate(
+        self,
+        messages: List[BaseMessage],
+        stop: Optional[List[str]] = None,
+        run_manager: Optional[AsyncCallbackManagerForLLMRun] = None,
+        **kwargs: Any,
+    ) -> LCChatResult:
+        kw = self._chat_kwargs(stop=stop, **kwargs)
+        result = await self._get_async().chat(messages_to_idemcore(messages), **kw)
+        message = _ai_message(result)
+        payload = receipt_payload(result)
+        return LCChatResult(
+            generations=[ChatGeneration(message=message, generation_info=payload, text=result.text)],
+            llm_output=payload,
+        )
+
+    def _stream(
+        self,
+        messages: List[BaseMessage],
+        stop: Optional[List[str]] = None,
+        run_manager: Optional[CallbackManagerForLLMRun] = None,
+        **kwargs: Any,
+    ) -> Iterator[ChatGenerationChunk]:
+        kw = self._chat_kwargs(stop=stop, **kwargs)
+        stream = self._get_sync().chat_stream(messages_to_idemcore(messages), **kw)
+        for chunk in stream:
+            if not chunk.delta:
+                continue
+            cg = ChatGenerationChunk(message=AIMessageChunk(content=chunk.delta), text=chunk.delta)
+            if run_manager:
+                run_manager.on_llm_new_token(chunk.delta, chunk=cg)
+            yield cg
+        result = stream.result
+        if result is None:
+            raise RuntimeError("Idemcore stream ended without a signed receipt.")
+        payload = receipt_payload(result)
+        final = ChatGenerationChunk(
+            message=AIMessageChunk(
+                content="",
+                response_metadata=payload,
+                additional_kwargs={"idemcore": payload},
+                usage_metadata=_usage_metadata(result),
+            ),
+            generation_info=payload,
+            text="",
+        )
+        yield final
+
+    async def _astream(
+        self,
+        messages: List[BaseMessage],
+        stop: Optional[List[str]] = None,
+        run_manager: Optional[AsyncCallbackManagerForLLMRun] = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[ChatGenerationChunk]:
+        kw = self._chat_kwargs(stop=stop, **kwargs)
+        stream = await self._get_async().chat_stream(messages_to_idemcore(messages), **kw)
+        async for chunk in stream:
+            if not chunk.delta:
+                continue
+            cg = ChatGenerationChunk(message=AIMessageChunk(content=chunk.delta), text=chunk.delta)
+            if run_manager:
+                await run_manager.on_llm_new_token(chunk.delta, chunk=cg)
+            yield cg
+        result = stream.result
+        if result is None:
+            raise RuntimeError("Idemcore stream ended without a signed receipt.")
+        payload = receipt_payload(result)
+        yield ChatGenerationChunk(
+            message=AIMessageChunk(
+                content="",
+                response_metadata=payload,
+                additional_kwargs={"idemcore": payload},
+                usage_metadata=_usage_metadata(result),
+            ),
+            generation_info=payload,
+            text="",
+        )

langchain_idemcore-0.1.0/src/langchain_idemcore/verify.py

@@ -0,0 +1,113 @@
+"""Verify receipts attached to LangChain results.
+
+Full receipt checks (signature, token-log chain when a log is provided, and
+prompt/answer commitments) use ``idemcore.verify_receipt``. When a public
+token log is supplied, it is also checked with the open ``idemcore-verify``
+package (``parse_log`` + ``check_log``).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
+
+from idemcore import VerificationResult, verify_receipt
+from idemcore_verify.core import check_log, parse_log
+
+from ._receipt import extract_receipt_payload
+
+
+@dataclass
+class VerificationBundle:
+    """Combined result of receipt verification and an optional public-log check."""
+
+    ok: bool
+    receipt: Dict[str, Any]
+    receipt_id: str
+    verification: VerificationResult
+    log_ok: Optional[bool] = None
+    log_errors: List[str] = field(default_factory=list)
+    log_details: Dict[str, Any] = field(default_factory=dict)
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+def verify_langchain_receipt(
+    source: Any,
+    *,
+    log_text: Optional[str] = None,
+    messages: Optional[Sequence[Mapping[str, Any]]] = None,
+    salt: Optional[str] = None,
+    output_text: Optional[str] = None,
+    output_token_ids: Optional[Sequence[int]] = None,
+    keys: Any = None,
+    check_signature: bool = True,
+    check_public_log: bool = True,
+) -> VerificationBundle:
+    """Verify a receipt taken from a LangChain message, ChatResult, or payload dict.
+
+    Parameters
+    ----------
+    source:
+        An ``AIMessage``, LangChain ``ChatResult`` / ``LLMResult``, an Idemcore
+        ``ChatResult``, or a mapping that contains ``receipt`` / ``receipt_id``.
+    log_text:
+        Public token log text. Enables the L2 chain check inside
+        ``idemcore.verify_receipt`` and, when ``check_public_log`` is true, a
+        standalone ``idemcore-verify`` log check.
+    messages, salt, output_text, output_token_ids:
+        Disclosure values used to confirm the receipt commits to this prompt
+        and answer. When omitted, values stored on ``source`` are used if present.
+    """
+    payload = extract_receipt_payload(source)
+    if not payload or not payload.get("receipt"):
+        raise ValueError("No Idemcore receipt found on the given object.")
+    receipt = dict(payload["receipt"])
+    receipt_id = payload.get("receipt_id") or receipt.get("receipt_id") or ""
+    if salt is None:
+        salt = payload.get("salt")
+    if output_text is None:
+        content = getattr(source, "content", None)
+        if isinstance(content, str) and content:
+            output_text = content
+    if messages is None:
+        # ChatResult (SDK) keeps the exact messages that were sent.
+        maybe = getattr(source, "messages", None)
+        if maybe:
+            messages = list(maybe)
+
+    verification = verify_receipt(
+        receipt,
+        keys=keys,
+        log_text=log_text,
+        messages=messages,
+        salt=salt,
+        output_token_ids=output_token_ids,
+        output_text=output_text,
+        check_signature=check_signature,
+    )
+
+    log_ok: Optional[bool] = None
+    log_errors: List[str] = []
+    log_details: Dict[str, Any] = {}
+    if log_text and check_public_log:
+        parsed = parse_log("<memory>", lines=log_text.splitlines())
+        checked = check_log(parsed)
+        log_ok = bool(checked.ok) and not parsed.errors
+        log_errors = list(parsed.errors) + list(checked.errors)
+        log_details = {
+            "n_tokens": checked.n_tokens,
+            "all_claimed": checked.all_claimed,
+            "all_recomputed": checked.all_recomputed,
+        }
+
+    ok = bool(verification.ok) and (log_ok is not False)
+    return VerificationBundle(
+        ok=ok,
+        receipt=receipt,
+        receipt_id=receipt_id,
+        verification=verification,
+        log_ok=log_ok,
+        log_errors=log_errors,
+        log_details=log_details,
+    )

langchain_idemcore-0.1.0/src/langchain_idemcore.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: langchain-idemcore
+Version: 0.1.0
+Summary: LangChain chat model for Idemcore, with signed verifiable receipts in response metadata.
+Author-email: Don Wick <don.wick@idemcore.net>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://idemcore.net
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: idemcore<0.4,>=0.3.0
+Requires-Dist: idemcore-verify<0.4,>=0.3.6
+Requires-Dist: langchain-core>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+
+# langchain-idemcore
+
+LangChain chat model for the [Idemcore](https://idemcore.net) API. Every answer
+comes with a signed, independently verifiable, bit-exact receipt, stored on
+`AIMessage.response_metadata`.
+
+Private package. Do not publish to PyPI without explicit approval.
+
+## Install (local)
+
+```bash
+pip install -e /workspace/idemcore-integrations/packages/langchain-idemcore
+export IDEMCORE_API_KEY=ick_...
+```
+
+Requires `idemcore>=0.3` (r2 receipts) and `idemcore-verify>=0.3.6`.
+
+## Quickstart
+
+```python
+from langchain_core.messages import HumanMessage
+from langchain_idemcore import ChatIdemcore, IdemcoreReceiptHandler, verify_langchain_receipt
+
+llm = ChatIdemcore(model="your-model-id", max_tokens=64)
+handler = IdemcoreReceiptHandler()
+
+msg = llm.invoke(
+    [HumanMessage(content="Name the three primary colours.")],
+    config={"callbacks": [handler]},
+)
+print(msg.content)
+print(msg.response_metadata["receipt_id"])   # rcpt_...
+print(handler.to_jsonl())
+
+# Local check of the signed receipt (and of a public token log, if you have one):
+# bundle = verify_langchain_receipt(msg, log_text=log_text)
+# print(bundle.ok, bundle.verification.levels)
+```
+
+Streaming works the same way: text arrives in chunks, and the receipt is
+attached to a later chunk's `response_metadata` once the answer is complete.
+Merging the `AIMessageChunk`s (or using `IdemcoreReceiptHandler`) preserves it.
+
+```python
+for chunk in llm.stream([HumanMessage(content="Write one short sentence.")]):
+    print(chunk.content, end="")
+```
+
+## Receipt metadata
+
+`AIMessage.response_metadata` (and `ChatResult.llm_output`) contains:
+
+- `receipt_id`, `receipt` (the full signed r2 receipt)
+- `salt` (for `hash_only` receipts; store it with the conversation)
+- `privacy`, `model`, `finish_reason`, `id`, `usage`
+
+`IdemcoreReceiptHandler` collects those payloads for a whole run and can write
+them as JSONL.
+
+`verify_langchain_receipt` runs `idemcore.verify_receipt` (signature, optional
+token-log chain, optional prompt/answer commitments). When `log_text` is
+given it also runs the open `idemcore-verify` log check.
+
+## Sampling
+
+Idemcore decoding is greedy: **temperature is fixed at 0**. Passing any other
+temperature, or sampling settings such as `top_p`, `top_k`, penalties, `seed`,
+`n`, or stop sequences, raises an error before a request is made. Tool and
+function calling are not supported.
+
+`max_tokens` must be a whole number from 1 to 2048. `privacy` is `hash_only`
+(default) or `full`. Auth is `IDEMCORE_API_KEY` (or `api_key=`). Billing is
+measured server-side in tokens.
+
+## Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+Unit tests mock the SDK. A live smoke test runs only when `IDEMCORE_API_KEY`
+is set in the environment.

langchain_idemcore-0.1.0/src/langchain_idemcore.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+src/langchain_idemcore/__init__.py
+src/langchain_idemcore/_convert.py
+src/langchain_idemcore/_receipt.py
+src/langchain_idemcore/callback.py
+src/langchain_idemcore/chat_models.py
+src/langchain_idemcore/py.typed
+src/langchain_idemcore/verify.py
+src/langchain_idemcore.egg-info/PKG-INFO
+src/langchain_idemcore.egg-info/SOURCES.txt
+src/langchain_idemcore.egg-info/dependency_links.txt
+src/langchain_idemcore.egg-info/requires.txt
+src/langchain_idemcore.egg-info/top_level.txt
+tests/test_callback_jsonl.py
+tests/test_chat_models.py
+tests/test_langchain_verify.py

langchain_idemcore-0.1.0/src/langchain_idemcore.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

langchain_idemcore-0.1.0/src/langchain_idemcore.egg-info/requires.txt

@@ -0,0 +1,7 @@
+idemcore<0.4,>=0.3.0
+idemcore-verify<0.4,>=0.3.6
+langchain-core>=0.3.0
+
+[dev]
+pytest>=8
+pytest-asyncio>=0.24

langchain_idemcore-0.1.0/src/langchain_idemcore.egg-info/top_level.txt

@@ -0,0 +1 @@
+langchain_idemcore

langchain_idemcore-0.1.0/tests/test_callback_jsonl.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from uuid import uuid4
+
+from langchain_core.messages import AIMessage
+from langchain_core.outputs import ChatGeneration, LLMResult
+
+from langchain_idemcore import IdemcoreReceiptHandler
+from langchain_idemcore._receipt import receipt_payload
+from tests.conftest import make_result
+
+
+def test_handler_dump_jsonl(tmp_path):
+    result = make_result()
+    payload = receipt_payload(result)
+    message = AIMessage(content=result.text, response_metadata=payload)
+    llm_result = LLMResult(generations=[[ChatGeneration(message=message, generation_info=payload)]])
+    handler = IdemcoreReceiptHandler()
+    handler.on_llm_end(llm_result, run_id=uuid4())
+    path = tmp_path / "receipts.jsonl"
+    handler.dump_jsonl(path)
+    text = path.read_text(encoding="utf-8")
+    assert result.receipt_id in text
+    assert text.endswith("\n")
+    handler.clear()
+    assert handler.to_list() == []
+    assert handler.to_jsonl() == ""

langchain_idemcore-0.1.0/tests/test_chat_models.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import os
+
+import pytest
+from idemcore import InvalidRequestError
+from langchain_core.messages import AIMessage, HumanMessage, SystemMessage, ToolMessage
+
+from langchain_idemcore import ChatIdemcore, IdemcoreReceiptHandler
+from langchain_idemcore._convert import UnsupportedMessageError
+from tests.conftest import FakeAsyncClient, FakeClient, make_result
+
+
+def _model(client, async_client=None) -> ChatIdemcore:
+    llm = ChatIdemcore(model="demo-model", max_tokens=64, privacy="hash_only")
+    llm._sync_client = client
+    llm._async_client = async_client or FakeAsyncClient(client.result)
+    return llm
+
+
+def test_invoke_attaches_receipt_to_response_metadata():
+    result = make_result()
+    client = FakeClient(result)
+    llm = _model(client)
+    handler = IdemcoreReceiptHandler()
+
+    msg = llm.invoke(
+        [SystemMessage(content="Be brief."), HumanMessage(content="Name the three primary colours.")],
+        config={"callbacks": [handler]},
+    )
+
+    assert isinstance(msg, AIMessage)
+    assert msg.content == "red green blue"
+    assert msg.response_metadata["receipt_id"] == result.receipt_id
+    assert msg.response_metadata["receipt"]["receipt_version"] == "r2"
+    assert msg.response_metadata["salt"] == "c2FsdA"
+    assert msg.additional_kwargs["idemcore"]["receipt_id"] == result.receipt_id
+    assert msg.usage_metadata["total_tokens"] == 11
+    assert client.last_messages == [
+        {"role": "system", "content": "Be brief."},
+        {"role": "user", "content": "Name the three primary colours."},
+    ]
+    assert client.last_kwargs["model"] == "demo-model"
+    assert client.last_kwargs["max_tokens"] == 64
+    assert client.last_kwargs["privacy"] == "hash_only"
+    assert len(handler.receipts) == 1
+    assert handler.receipts[0]["receipt_id"] == result.receipt_id
+    assert "run_id" in handler.receipts[0]
+    jsonl = handler.to_jsonl()
+    assert result.receipt_id in jsonl
+    assert jsonl.endswith("\n")
+
+
+@pytest.mark.asyncio
+async def test_ainvoke_attaches_receipt():
+    result = make_result(text="ok")
+    async_client = FakeAsyncClient(result)
+    llm = _model(FakeClient(result), async_client)
+    msg = await llm.ainvoke([HumanMessage(content="Hi")])
+    assert msg.content == "ok"
+    assert msg.response_metadata["receipt_id"] == result.receipt_id
+    assert async_client.last_messages == [{"role": "user", "content": "Hi"}]
+
+
+def test_stream_attaches_receipt_on_final_chunk():
+    result = make_result(text="abc")
+    llm = _model(FakeClient(result, stream_text="abc"))
+    chunks = list(llm.stream([HumanMessage(content="go")]))
+    text = "".join(c.content for c in chunks)
+    assert text == "abc"
+    # LangChain may append an empty trailing chunk; the receipt is on a chunk
+    # and is preserved when AIMessageChunks are merged.
+    with_receipt = [c for c in chunks if c.response_metadata.get("receipt_id")]
+    assert with_receipt
+    assert with_receipt[0].response_metadata["receipt_id"] == result.receipt_id
+    assert with_receipt[0].response_metadata["receipt"]["receipt_version"] == "r2"
+    merged = chunks[0]
+    for c in chunks[1:]:
+        merged = merged + c
+    assert merged.response_metadata["receipt_id"] == result.receipt_id
+
+
+@pytest.mark.asyncio
+async def test_astream_attaches_receipt_on_final_chunk():
+    result = make_result(text="xyz")
+    async_client = FakeAsyncClient(result, stream_text="xyz")
+    llm = _model(FakeClient(result), async_client)
+    chunks = [c async for c in llm.astream([HumanMessage(content="go")])]
+    assert "".join(c.content for c in chunks) == "xyz"
+    with_receipt = [c for c in chunks if c.response_metadata.get("receipt_id")]
+    assert with_receipt and with_receipt[0].response_metadata["receipt_id"] == result.receipt_id
+
+
+def test_rejects_nonzero_temperature():
+    llm = _model(FakeClient(make_result()))
+    with pytest.raises(InvalidRequestError, match="temperature is fixed at 0"):
+        llm.invoke([HumanMessage(content="hi")], temperature=0.7)
+
+
+def test_rejects_top_p_and_seed():
+    llm = _model(FakeClient(make_result()))
+    with pytest.raises(InvalidRequestError, match="sampling"):
+        llm.invoke([HumanMessage(content="hi")], top_p=0.9)
+    with pytest.raises(InvalidRequestError, match="sampling"):
+        llm.invoke([HumanMessage(content="hi")], seed=1)
+
+
+def test_rejects_stop_sequences():
+    llm = _model(FakeClient(make_result()))
+    with pytest.raises(InvalidRequestError, match="stop sequences"):
+        llm.invoke([HumanMessage(content="hi")], stop=["\n"])
+
+
+def test_rejects_tool_messages_and_bind_tools():
+    llm = _model(FakeClient(make_result()))
+    with pytest.raises(UnsupportedMessageError):
+        llm.invoke([HumanMessage(content="hi"), ToolMessage(content="tool", tool_call_id="1")])
+    with pytest.raises(NotImplementedError, match="tool calling"):
+        llm.bind_tools([{"type": "function", "function": {"name": "x"}}])
+
+
+def test_temperature_zero_is_allowed():
+    client = FakeClient(make_result())
+    llm = _model(client)
+    llm.invoke([HumanMessage(content="hi")], temperature=0)
+    assert client.last_kwargs.get("temperature") == 0
+
+
+@pytest.mark.skipif(not os.environ.get("IDEMCORE_API_KEY"), reason="IDEMCORE_API_KEY not set")
+def test_live_smoke_chat():
+    llm = ChatIdemcore(max_tokens=16)
+    models = llm._get_sync().models()
+    assert models, "API returned no models"
+    llm.model = models[0]["id"]
+    handler = IdemcoreReceiptHandler()
+    msg = llm.invoke(
+        [HumanMessage(content="Reply with the single word yes.")],
+        config={"callbacks": [handler]},
+    )
+    assert msg.content
+    assert msg.response_metadata.get("receipt_id", "").startswith("rcpt_")
+    assert handler.receipts

langchain_idemcore-0.1.0/tests/test_langchain_verify.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+from idemcore import VerificationResult
+from idemcore.verify import LevelResult
+
+from langchain_idemcore import verify_langchain_receipt
+from langchain_idemcore._receipt import receipt_payload
+from tests.conftest import make_result
+
+
+def test_verify_helper_uses_sdk_and_open_verifier(monkeypatch):
+    result = make_result()
+    payload = receipt_payload(result)
+    message = SimpleNamespace(content=result.text, response_metadata=payload, messages=result.messages)
+
+    calls = {}
+
+    def fake_verify_receipt(receipt, **kwargs):
+        calls["verify"] = {"receipt": receipt, **kwargs}
+        return VerificationResult(
+            ok=True,
+            levels={"L1": LevelResult(level="L1", ok=True)},
+        )
+
+    class FakeChecked:
+        ok = True
+        n_tokens = 2
+        all_claimed = "0123456789abcdef"
+        all_recomputed = "0123456789abcdef"
+        errors = []
+
+    class FakeParsed:
+        errors = []
+
+    def fake_parse_log(path, lines=None):
+        calls["parse"] = {"path": path, "lines": list(lines)}
+        return FakeParsed()
+
+    def fake_check_log(log):
+        calls["check"] = log
+        return FakeChecked()
+
+    monkeypatch.setattr("langchain_idemcore.verify.verify_receipt", fake_verify_receipt)
+    monkeypatch.setattr("langchain_idemcore.verify.parse_log", fake_parse_log)
+    monkeypatch.setattr("langchain_idemcore.verify.check_log", fake_check_log)
+
+    log_text = "0 0 0123456789abcdef 0123456789abcdef\nALL 0123456789abcdef\n"
+    bundle = verify_langchain_receipt(message, log_text=log_text)
+
+    assert bundle.ok is True
+    assert bundle.receipt_id == result.receipt_id
+    assert calls["verify"]["receipt"]["receipt_id"] == result.receipt_id
+    assert calls["verify"]["log_text"] == log_text
+    assert calls["verify"]["salt"] == result.salt
+    assert calls["verify"]["output_text"] == result.text
+    assert calls["parse"]["path"] == "<memory>"
+    assert bundle.log_ok is True
+    assert bundle.log_details["n_tokens"] == 2
+
+
+def test_verify_helper_requires_a_receipt():
+    with pytest.raises(ValueError, match="No Idemcore receipt"):
+        verify_langchain_receipt({"foo": "bar"})