langchain-valen 0.1.0__tar.gz

langchain_valen-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+*.tgz
+*.difypkg
+__pycache__/
+.venv/
+.DS_Store

langchain_valen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valen Team
+
+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_valen-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: langchain-valen
+Version: 0.1.0
+Summary: Typed Valen decisions and uncertainty-aware routing for LangChain and LangGraph
+Project-URL: Repository, https://github.com/Valen-Team/valen-integrations
+Project-URL: Documentation, https://github.com/Valen-Team/valen-integrations/tree/main/langchain
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2,>=1.0
+Requires-Dist: valen-sdk<0.4,>=0.3.1
+Provides-Extra: test
+Requires-Dist: build>=1; extra == 'test'
+Requires-Dist: langgraph<2,>=1; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: twine<7,>=6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# LangChain Valen
+
+[中文](README_zh.md)
+
+Add ticket routing, image checks and structured judgments to your LangChain app. Valen returns named answers and probabilities you can use directly in LCEL, agent tools and LangGraph conditional edges. Keep the routing rules and review thresholds in your application.
+
+## Install
+
+```sh
+python -m pip install langchain-valen==0.1.0
+```
+
+[View on PyPI](https://pypi.org/project/langchain-valen/)
+
+Requires Python 3.10+, `langchain-core` 1.x and `valen-sdk` 0.3.x. The wheel does not include model weights. LangGraph examples additionally need `python -m pip install 'langgraph>=1,<2'`.
+
+## Evaluate
+
+```python
+from langchain_valen import ValenEvaluator
+
+evaluate = ValenEvaluator([
+    {"name": "refund", "type": "predicate",
+     "instructions": "The customer requests a refund."},
+])
+result = evaluate.invoke("I was charged twice. Please refund the duplicate charge.")
+print(result["answers"]["refund"]["probability"])
+```
+
+The default free API needs no key. For a keyed server, pass `base_url` and `api_key` or set `VALEN_API_KEY`. A trailing `/v1` is optional. `model` defaults to `valen-2b`; self-hosted names work too. Each call uses the SDK's 120-second timeout per attempt and two retries for supported transient failures; `timeout` and `max_retries` are configurable.
+
+Input can be text, a JSON object/array, or an envelope `{"input": ..., "image": image_bytes}`. Use the envelope for structured evidence containing a field named `input`. Images must be PNG, JPEG or WebP bytes, one per request. Download URLs yourself before invoking; this prevents hidden network fetches in the runnable.
+
+Evaluate returns `{"answers": {question_name: answer}, "model": resolved_model_id}`. Choice answers include `choice`, `confidence`, and candidate probabilities; Score includes expected `score`, most likely `level`, confidence and probabilities. Probabilities are retained without rounding.
+
+## Route once in LCEL
+
+```python
+from langchain_core.runnables import RunnablePassthrough
+from langchain_valen import ValenRouter
+
+router = ValenRouter({
+    "name": "refund", "type": "predicate",
+    "instructions": "The customer requests a refund.",
+}, yes_at=0.7, no_at=0.3)
+chain = RunnablePassthrough.assign(branch=router)
+print(chain.invoke({"input": "Please refund my order."}))
+```
+
+The router returns `yes`, `no` or `unsure`. Require `0 ≤ no_at < yes_at ≤ 1`. Choice returns the selected candidate value; Score returns the most probable level (earlier level on ties). Choice must have an explicit outside-scope candidate when none may fit. Choice and Score have no automatic uncertainty gate; use an Evaluator and your own rule if you need one.
+
+`invoke`, `batch`, `ainvoke` and runnable composition use LangChain's interfaces. Async calls use its executor bridge around the synchronous SDK client. A supplied `client=` is caller-owned and must support `predict(payload)`; do not share a non-thread-safe local client across concurrent batches.
+
+## LangGraph
+
+[`examples/support_routing.py`](examples/support_routing.py) builds a real graph with billing, technical and review destinations, then runs three synthetic tickets:
+
+```sh
+python -m langchain_valen.example
+```
+
+Use `router` directly in `builder.add_conditional_edges("judge", router, branch_map)`. The example makes no external business actions. Its predictions are a demonstration, not an accuracy guarantee.
+
+## Agent tool and failures
+
+```python
+from langchain_valen import ValenDecisionTool
+
+tool = ValenDecisionTool(evaluator=evaluate)
+print(tool.invoke({"input": "Please refund the duplicate charge."}))
+```
+
+The tool exposes a text-input schema and returns the same named answers. It raises `ToolException` on failure, so LangChain's `handle_tool_error` policy works. Evaluators and routers raise errors directly; failures never become a branch or a probability. Invalid questions, thresholds, incomplete responses and unsupported image formats fail explicitly.
+
+The integration adds no storage or logs. Evidence and questions go to your configured endpoint; LangChain tracing and endpoint retention settings still apply. See [Valen data handling](https://valen-team.github.io/docs/valen/api/data-handling/).
+
+## Development
+
+Run the root tests with the `test` extras installed. Tests exercise the real SDK against a local fixture server, real LangGraph edges, LCEL composition and tool error handling; fixtures do not measure model accuracy. Run the example separately for live inference. Shared validation is generated from `shared/protocol.py`; update it with `python scripts/build_shared.py` before building.

langchain_valen-0.1.0/README.md

@@ -0,0 +1,79 @@
+# LangChain Valen
+
+[中文](README_zh.md)
+
+Add ticket routing, image checks and structured judgments to your LangChain app. Valen returns named answers and probabilities you can use directly in LCEL, agent tools and LangGraph conditional edges. Keep the routing rules and review thresholds in your application.
+
+## Install
+
+```sh
+python -m pip install langchain-valen==0.1.0
+```
+
+[View on PyPI](https://pypi.org/project/langchain-valen/)
+
+Requires Python 3.10+, `langchain-core` 1.x and `valen-sdk` 0.3.x. The wheel does not include model weights. LangGraph examples additionally need `python -m pip install 'langgraph>=1,<2'`.
+
+## Evaluate
+
+```python
+from langchain_valen import ValenEvaluator
+
+evaluate = ValenEvaluator([
+    {"name": "refund", "type": "predicate",
+     "instructions": "The customer requests a refund."},
+])
+result = evaluate.invoke("I was charged twice. Please refund the duplicate charge.")
+print(result["answers"]["refund"]["probability"])
+```
+
+The default free API needs no key. For a keyed server, pass `base_url` and `api_key` or set `VALEN_API_KEY`. A trailing `/v1` is optional. `model` defaults to `valen-2b`; self-hosted names work too. Each call uses the SDK's 120-second timeout per attempt and two retries for supported transient failures; `timeout` and `max_retries` are configurable.
+
+Input can be text, a JSON object/array, or an envelope `{"input": ..., "image": image_bytes}`. Use the envelope for structured evidence containing a field named `input`. Images must be PNG, JPEG or WebP bytes, one per request. Download URLs yourself before invoking; this prevents hidden network fetches in the runnable.
+
+Evaluate returns `{"answers": {question_name: answer}, "model": resolved_model_id}`. Choice answers include `choice`, `confidence`, and candidate probabilities; Score includes expected `score`, most likely `level`, confidence and probabilities. Probabilities are retained without rounding.
+
+## Route once in LCEL
+
+```python
+from langchain_core.runnables import RunnablePassthrough
+from langchain_valen import ValenRouter
+
+router = ValenRouter({
+    "name": "refund", "type": "predicate",
+    "instructions": "The customer requests a refund.",
+}, yes_at=0.7, no_at=0.3)
+chain = RunnablePassthrough.assign(branch=router)
+print(chain.invoke({"input": "Please refund my order."}))
+```
+
+The router returns `yes`, `no` or `unsure`. Require `0 ≤ no_at < yes_at ≤ 1`. Choice returns the selected candidate value; Score returns the most probable level (earlier level on ties). Choice must have an explicit outside-scope candidate when none may fit. Choice and Score have no automatic uncertainty gate; use an Evaluator and your own rule if you need one.
+
+`invoke`, `batch`, `ainvoke` and runnable composition use LangChain's interfaces. Async calls use its executor bridge around the synchronous SDK client. A supplied `client=` is caller-owned and must support `predict(payload)`; do not share a non-thread-safe local client across concurrent batches.
+
+## LangGraph
+
+[`examples/support_routing.py`](examples/support_routing.py) builds a real graph with billing, technical and review destinations, then runs three synthetic tickets:
+
+```sh
+python -m langchain_valen.example
+```
+
+Use `router` directly in `builder.add_conditional_edges("judge", router, branch_map)`. The example makes no external business actions. Its predictions are a demonstration, not an accuracy guarantee.
+
+## Agent tool and failures
+
+```python
+from langchain_valen import ValenDecisionTool
+
+tool = ValenDecisionTool(evaluator=evaluate)
+print(tool.invoke({"input": "Please refund the duplicate charge."}))
+```
+
+The tool exposes a text-input schema and returns the same named answers. It raises `ToolException` on failure, so LangChain's `handle_tool_error` policy works. Evaluators and routers raise errors directly; failures never become a branch or a probability. Invalid questions, thresholds, incomplete responses and unsupported image formats fail explicitly.
+
+The integration adds no storage or logs. Evidence and questions go to your configured endpoint; LangChain tracing and endpoint retention settings still apply. See [Valen data handling](https://valen-team.github.io/docs/valen/api/data-handling/).
+
+## Development
+
+Run the root tests with the `test` extras installed. Tests exercise the real SDK against a local fixture server, real LangGraph edges, LCEL composition and tool error handling; fixtures do not measure model accuracy. Run the example separately for live inference. Shared validation is generated from `shared/protocol.py`; update it with `python scripts/build_shared.py` before building.

langchain_valen-0.1.0/README_zh.md

@@ -0,0 +1,36 @@
+# 在 LangChain 与 LangGraph 中使用 Valen
+
+[English](README.md)
+
+为 LangChain 应用增加工单分流、图片检查和告警分级。写下要判断的问题，即可得到有名称的答案与概率，直接用于 LCEL、LangGraph 分支或 Agent 工具。人工复核阈值和后续动作由你的应用控制。
+
+## 安装与首次运行
+
+```sh
+python -m pip install langchain-valen==0.1.0
+```
+
+需要 Python 3.10+，安装时会自动获取 LangChain Core 和 Valen SDK。[PyPI 包](https://pypi.org/project/langchain-valen/)
+
+```python
+from langchain_valen import ValenEvaluator
+
+client = ValenEvaluator([
+    {"name": "refund", "type": "predicate", "instructions": "客户要求退款。"}
+])
+print(client.invoke("我被重复扣款了，请退还多收的钱。"))
+```
+
+默认调用免费 API，无需密钥。带密钥的服务可传 `base_url`、`api_key`，也可设置 `VALEN_API_KEY` 环境变量。不要把密钥写入示例或提交到仓库。
+
+输入支持文本、JSON，以及 `{"input": 内容, "image": 图片字节}`；一次最多一张 PNG、JPEG 或 WebP，最多 8 个问题。
+
+## 分流与实际工作流
+
+`ValenRouter(question, yes_at=0.7, no_at=0.3)` 对是否题返回 `yes`、`no`、`unsure`。Choice 返回选项值，Score 返回概率最高的等级（平局取靠前等级），不是对期望分数四舍五入。
+
+安装 `langgraph` 后运行 `python -m langchain_valen.example`，即可在实际 LangGraph 中把三条合成工单分到账单、技术和人工复核。示例不执行外部业务动作。
+
+失败会抛出异常，不会伪装为正常分支。`ValenDecisionTool` 抛出标准 `ToolException`，可使用 LangChain 的 `handle_tool_error`。Choice 必须按需要提供范围外选项，低置信度规则留在工作流中。
+
+完整接口、异步行为和开发说明见[英文说明](README.md)。

langchain_valen-0.1.0/RELEASING.md

@@ -0,0 +1,32 @@
+# Build, release and upgrade
+
+Run from the repository root with Python 3.12:
+
+```sh
+python scripts/build_shared.py --check
+python -m pip install -r dify/requirements.txt -e './langchain[test]'
+python -m pytest tests coze/tests
+python -m build langchain --outdir artifacts/langchain
+python -m twine check artifacts/langchain/*
+```
+
+Install the wheel in a separate environment outside the checkout. Run the LangChain
+contract tests against that installation and run `python -m langchain_valen.example` with
+synthetic data against the configured Valen API. Check an image and a failed request too.
+The repository's Python workflow builds artifacts; it does not publish them.
+
+The release.yml workflow builds, tests and publishes on matching langchain-v* tags. Configure the PyPI trusted publisher for Valen-Team/valen-integrations and workflow release.yml first (https://docs.pypi.org/trusted-publishers/using-a-publisher/). Preparing this workflow does not publish a package. An authorized release operator publishes the tested wheel and source archive to PyPI,
+using a scoped API token or configured Trusted Publishing. Keep credentials outside the
+repository. After publication, create a new environment and install the exact version
+from PyPI, repeat the example and record the public URL and artifact checksums in the
+acceptance record. A successful local build is not a published release.
+
+Before upgrading, retain the current pinned version and question/threshold configuration.
+Review changes to SPEC.md, update the package version and User-Agent together, regenerate
+shared code, and run the same synthetic workflow in the target LangChain/LangGraph versions.
+Rollback by reinstalling the previous pinned package and restoring the matching question set.
+
+The release job also accepts the PYPI_API_TOKEN repository secret for account-authorized
+bootstrap publishing. Without that secret it uses the configured trusted publisher.
+No secret has been uploaded to GitHub and no publication was triggered while preparing
+this workflow.

langchain_valen-0.1.0/examples/support_routing.py

@@ -0,0 +1,33 @@
+"""Run with a real Valen endpoint, or point VALEN_BASE_URL at a local fixture server."""
+import os
+from typing import TypedDict
+from langgraph.graph import StateGraph, START, END
+from langchain_valen import ValenRouter
+
+
+class State(TypedDict):
+    input: str
+    team: str
+
+
+router = ValenRouter({
+    'name': 'team', 'type': 'choice', 'instructions': 'Which team should handle this ticket?',
+    'choices': [
+        {'value': 'billing', 'description': 'Payments, duplicate charges and refunds'},
+        {'value': 'technical', 'description': 'Software bugs and crashes'},
+        {'value': 'review', 'description': 'Outside billing and technical support, or too little information'},
+    ],
+}, base_url=os.environ.get('VALEN_BASE_URL', 'https://api.valen-team.workers.dev'))
+
+builder = StateGraph(State)
+builder.add_node('judge', lambda state: state)
+builder.add_edge(START, 'judge')
+builder.add_conditional_edges('judge', router, {k: k for k in ('billing', 'technical', 'review')})
+for team in ('billing', 'technical', 'review'):
+    builder.add_node(team, lambda state, team=team: {'team': team})
+    builder.add_edge(team, END)
+graph = builder.compile()
+
+if __name__ == '__main__':
+    for text in ('I was charged twice. Please help.', 'The app crashes.', 'Can you recommend a birthday gift?'):
+        print(graph.invoke({'input': text}))

langchain_valen-0.1.0/langchain_valen/__init__.py

@@ -0,0 +1,6 @@
+"""Valen decisions for LangChain. Input data is sent only to the configured endpoint."""
+from .runnables import ValenEvaluator, ValenRouter
+from .tools import ValenDecisionTool
+
+__all__ = ['ValenEvaluator', 'ValenRouter', 'ValenDecisionTool']
+__version__ = '0.1.0'

langchain_valen-0.1.0/langchain_valen/_protocol.py

@@ -0,0 +1,162 @@
+# Generated from shared/protocol.py by scripts/build_shared.py. Do not edit.
+"""Platform-neutral Valen workflow rules. Vendored by scripts/build_shared.py."""
+import base64
+import json
+import math
+import re
+from urllib.parse import urlsplit
+
+
+def endpoint(value):
+    parts = urlsplit(value)
+    if parts.scheme not in ('http', 'https') or not parts.netloc or parts.username or parts.password or parts.query or parts.fragment:
+        raise ValueError('Base URL must be HTTP(S), without credentials, query or fragment')
+    return value.rstrip('/').removesuffix('/v1') + '/v1'
+
+
+def parse_lines(text):
+    result = []
+    for line in str(text or '').splitlines():
+        if not line.strip():
+            continue
+        value, sep, description = line.strip().partition(': ')
+        value, description = value.strip(), description.strip() if sep else value.strip()
+        if not value or not description:
+            raise ValueError('Options and descriptions must not be empty')
+        result.append((value, description))
+    if len(result) < 2 or len({p[0] for p in result}) != len(result):
+        raise ValueError('Use at least two distinct options or levels')
+    return result
+
+
+def validate_questions(value):
+    rows = json.loads(value) if isinstance(value, str) else value
+    if not isinstance(rows, list) or not rows:
+        raise ValueError('Use a nonempty questions array')
+    names = set()
+    for q in rows:
+        if not isinstance(q, dict) or not isinstance(q.get('name'), str) or not re.fullmatch(r'[A-Za-z0-9_]+', q['name']) or q['name'] in names:
+            raise ValueError('Question IDs must be unique letters, digits or underscores')
+        names.add(q['name'])
+        if not isinstance(q.get('instructions'), str) or not q['instructions'].strip():
+            raise ValueError('Each question needs instructions')
+        if q.get('type') not in ('predicate', 'choice', 'score'):
+            raise ValueError('Question type must be predicate, choice or score')
+        if q['type'] != 'predicate':
+            field, key = ('choices', 'value') if q['type'] == 'choice' else ('levels', 'label')
+            values = q.get(field)
+            if not isinstance(values, list) or len(values) < 2:
+                raise ValueError('Use at least two distinct, described choices or levels')
+            for v in values:
+                if not isinstance(v, dict) or not isinstance(v.get(key), str) or not v[key].strip() or not isinstance(v.get('description'), str) or not v['description'].strip():
+                    raise ValueError('Each choice or level needs a nonempty value and description')
+            if len({v[key] for v in values}) != len(values):
+                raise ValueError('Choice values or level labels must be distinct')
+    return rows
+
+
+def single_question(kind, instructions, lines=''):
+    q = {'name': 'q', 'type': kind, 'instructions': instructions}
+    if kind in ('choice', 'score'):
+        key = 'value' if kind == 'choice' else 'label'
+        q['choices' if kind == 'choice' else 'levels'] = [{key: v, 'description': d} for v, d in parse_lines(lines)]
+    return validate_questions([q])[0]
+
+
+def thresholds(yes_at=0.7, no_at=0.3):
+    if not all(isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v) for v in (yes_at, no_at)) or not 0 <= no_at < yes_at <= 1:
+        raise ValueError('Thresholds must satisfy 0 ≤ No at < Yes at ≤ 1')
+    return yes_at, no_at
+
+
+def probability(value):
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value) or not 0 <= value <= 1:
+        raise ValueError('API returned an invalid probability')
+    return value
+
+
+def map_answers(response, asked):
+    rows = response.get('answers') if isinstance(response, dict) else None
+    if not isinstance(rows, list) or len(rows) != len(asked):
+        raise ValueError('API returned an incomplete answer list')
+    mapped = {}
+    for q in asked:
+        matches = [a for a in rows if isinstance(a, dict) and a.get('name') == q['name']]
+        if len(matches) != 1 or matches[0].get('type') != q['type']:
+            raise ValueError('API returned a missing, duplicate or wrong-type answer')
+        a = matches[0]
+        if q['type'] == 'predicate':
+            mapped[q['name']] = {'probability': probability(a.get('probability'))}
+            continue
+        key = 'value' if q['type'] == 'choice' else 'label'
+        labels = [p[key] for p in q['choices' if q['type'] == 'choice' else 'levels']]
+        values = a.get('probabilities')
+        if not isinstance(values, list) or len(values) != len(labels):
+            raise ValueError('API returned incomplete probabilities')
+        distribution = {}
+        for v in values:
+            label = v.get(key) if isinstance(v, dict) else None
+            if label not in labels or label in distribution:
+                raise ValueError('API returned unknown or duplicate candidates')
+            distribution[label] = probability(v.get('probability'))
+        if abs(sum(distribution.values()) - 1) > 0.001:
+            raise ValueError('API probabilities do not sum to one')
+        answer = {'confidence': probability(a.get('confidence')), 'probabilities': distribution}
+        if q['type'] == 'choice':
+            if a.get('choice') not in labels:
+                raise ValueError('API returned an unknown choice')
+            answer['choice'] = a['choice']
+        else:
+            score = a.get('score')
+            if not isinstance(score, (int, float)) or isinstance(score, bool) or not math.isfinite(score) or not 0 <= score <= len(labels)-1:
+                raise ValueError('API returned an invalid score')
+            answer.update(score=score, level=max(labels, key=distribution.get))
+        mapped[q['name']] = answer
+    model = response.get('model_id') or response.get('model')
+    if not isinstance(model, str) or not model:
+        raise ValueError('API returned no model ID')
+    return {'answers': mapped, 'model': model}
+
+
+def route_answer(answer, kind, yes_at=0.7, no_at=0.3):
+    thresholds(yes_at, no_at)
+    if kind == 'predicate':
+        branch = 'yes' if answer['probability'] >= yes_at else 'no' if answer['probability'] <= no_at else 'unsure'
+    else:
+        branch = answer['choice' if kind == 'choice' else 'level']
+    return dict(answer, branch=branch)
+
+
+def image_type(data):
+    if data[:8] == b'\x89PNG\r\n\x1a\n':
+        return 'image/png'
+    if data[:3] == b'\xff\xd8\xff':
+        return 'image/jpeg'
+    if data[:4] == b'RIFF' and data[8:12] == b'WEBP':
+        return 'image/webp'
+    raise ValueError('Image must be PNG, JPEG or WebP')
+
+
+def api_error_message(error):
+    """Preserve SDK metadata when a platform only displays exception text."""
+    status = getattr(error, 'status_code', None)
+    request_id = getattr(error, 'request_id', None)
+    message = (f'HTTP {status}: ' if status is not None else '') + str(error)
+    if request_id:
+        message += f' (request ID: {request_id})'
+    if status == 429:
+        message += '; wait at least a minute before trying again'
+    return message
+
+
+def evidence(value, image=None):
+    if not isinstance(value, str):
+        if not isinstance(value, (dict, list)):
+            raise ValueError('Input must be text, a JSON object or array')
+        value = json.dumps(value, indent=2, ensure_ascii=False, allow_nan=False)
+    if image is None:
+        return value
+    if not isinstance(image, bytes):
+        raise ValueError('Image must be file bytes; download remote files before calling')
+    data_url = 'data:' + image_type(image) + ';base64,' + base64.b64encode(image).decode('ascii')
+    return [{'role': 'user', 'content': [{'type': 'input_text', 'text': value}, {'type': 'input_image', 'image_url': data_url}]}]

langchain_valen-0.1.0/langchain_valen/example.py

@@ -0,0 +1,33 @@
+"""Run with a real Valen endpoint, or point VALEN_BASE_URL at a local fixture server."""
+import os
+from typing import TypedDict
+from langgraph.graph import StateGraph, START, END
+from langchain_valen import ValenRouter
+
+
+class State(TypedDict):
+    input: str
+    team: str
+
+
+router = ValenRouter({
+    'name': 'team', 'type': 'choice', 'instructions': 'Which team should handle this ticket?',
+    'choices': [
+        {'value': 'billing', 'description': 'Payments, duplicate charges and refunds'},
+        {'value': 'technical', 'description': 'Software bugs and crashes'},
+        {'value': 'review', 'description': 'Outside billing and technical support, or too little information'},
+    ],
+}, base_url=os.environ.get('VALEN_BASE_URL', 'https://api.valen-team.workers.dev'))
+
+builder = StateGraph(State)
+builder.add_node('judge', lambda state: state)
+builder.add_edge(START, 'judge')
+builder.add_conditional_edges('judge', router, {k: k for k in ('billing', 'technical', 'review')})
+for team in ('billing', 'technical', 'review'):
+    builder.add_node(team, lambda state, team=team: {'team': team})
+    builder.add_edge(team, END)
+graph = builder.compile()
+
+if __name__ == '__main__':
+    for text in ('I was charged twice. Please help.', 'The app crashes.', 'Can you recommend a birthday gift?'):
+        print(graph.invoke({'input': text}))

langchain_valen-0.1.0/langchain_valen/runnables.py

@@ -0,0 +1,67 @@
+"""Runnable integrations, with routing rules kept outside the model."""
+import os
+from copy import deepcopy
+from typing import Any
+
+from langchain_core.runnables import Runnable, RunnableConfig
+from valen_sdk import Valen
+from valen_sdk.errors import ValenAPIError
+
+from ._protocol import api_error_message, endpoint, evidence, map_answers, route_answer, thresholds, validate_questions
+
+
+class ValenEvaluator(Runnable[Any, dict]):
+    """Ask a fixed question set. Input is text or {input, image?: bytes}.
+
+    Use ``{input: {...}}`` for structured evidence. A supplied client is caller-owned;
+    otherwise each invocation opens and closes a remote SDK client. ``ainvoke`` uses
+    LangChain's default executor bridge, leaving the event loop free.
+    """
+
+    name = "valen_evaluator"
+
+    def __init__(self, questions, *, base_url='https://api.valen-team.workers.dev', api_key=None,
+                 model='valen-2b', timeout=120.0, max_retries=2, client=None):
+        self.questions = deepcopy(validate_questions(questions))
+        self.base_url = endpoint(base_url)
+        self.api_key = api_key if api_key is not None else os.environ.get('VALEN_API_KEY')
+        self.model, self.timeout, self.max_retries = model, timeout, max_retries
+        self.client = client
+
+    def invoke(self, input, config: RunnableConfig | None = None, **kwargs):
+        if isinstance(input, dict) and 'input' in input:
+            value, image = input['input'], input.get('image')
+        else:
+            value, image = input, None
+        payload = {'input': evidence(value, image), 'questions': deepcopy(self.questions), 'model': self.model}
+        try:
+            if self.client is not None:
+                result = self.client.predict(payload)
+            else:
+                with Valen.remote(self.base_url, api_key=self.api_key, model=self.model,
+                                  timeout=self.timeout, max_retries=self.max_retries,
+                                  headers={'User-Agent': 'valen-langchain/0.1.0'}) as client:
+                    result = client.predict(payload)
+        except ValenAPIError as error:
+            raise RuntimeError(api_error_message(error)) from error
+        return map_answers(result, self.questions)
+
+
+class ValenRouter(Runnable[Any, str]):
+    """Return one branch key for LCEL or LangGraph conditional edges.
+
+    Yes/No yields yes/no/unsure. Choice yields a candidate value; Score yields the
+    most likely level (earlier level on ties), not rounded expected score.
+    """
+
+    name = "valen_router"
+
+    def __init__(self, question, *, yes_at=0.7, no_at=0.3, **kwargs):
+        self.yes_at, self.no_at = thresholds(yes_at, no_at)
+        self.evaluator = ValenEvaluator([question], **kwargs)
+        self.question = self.evaluator.questions[0]
+
+    def invoke(self, input, config: RunnableConfig | None = None, **kwargs):
+        result = self.evaluator.invoke(input, config=config)
+        answer = result['answers'][self.question['name']]
+        return route_answer(answer, self.question['type'], self.yes_at, self.no_at)['branch']

langchain_valen-0.1.0/langchain_valen/tools.py

@@ -0,0 +1,24 @@
+"""An agent tool with an explicit schema and standard LangChain error handling."""
+from typing import Any
+from pydantic import BaseModel, Field, ConfigDict
+from langchain_core.tools import BaseTool, ToolException
+from .runnables import ValenEvaluator
+from ._protocol import api_error_message
+
+
+class DecisionInput(BaseModel):
+    input: str = Field(description='Text to judge against the configured questions')
+
+
+class ValenDecisionTool(BaseTool):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    name: str = 'valen_decisions'
+    description: str = 'Evaluate text against configured Valen questions and return named probabilities.'
+    args_schema: type[BaseModel] = DecisionInput
+    evaluator: Any = Field(exclude=True, repr=False)
+
+    def _run(self, input: str):
+        try:
+            return self.evaluator.invoke(input)
+        except Exception as error:
+            raise ToolException(api_error_message(error)) from error

langchain_valen-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-valen"
+version = "0.1.0"
+description = "Typed Valen decisions and uncertainty-aware routing for LangChain and LangGraph"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = ["langchain-core>=1.0,<2", "valen-sdk>=0.3.1,<0.4"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "langgraph>=1,<2", "build>=1", "twine>=6,<7"]
+
+[project.urls]
+Repository = "https://github.com/Valen-Team/valen-integrations"
+Documentation = "https://github.com/Valen-Team/valen-integrations/tree/main/langchain"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_valen"]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.4"