langchain-aistupidlevel 0.1.0__tar.gz

langchain_aistupidlevel-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+build/
+*.tsbuildinfo
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.env
+.env.*
+*.db
+*.sqlite
+.DS_Store
+*.tgz

langchain_aistupidlevel-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Studio Platforms (AI Stupid Level)
+
+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_aistupidlevel-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: langchain-aistupidlevel
+Version: 0.1.0
+Summary: LangChain chat model for the AI Stupid Level Smart Router: each request goes to the model that scores best for the task, with your own provider keys.
+Project-URL: Homepage, https://aistupidlevel.info/router
+Project-URL: Documentation, https://aistupidlevel.info/router/docs#integrations
+Project-URL: Source, https://github.com/StudioPlatforms/aistupidlevel-sdk/tree/main/langchain-python
+Project-URL: Issues, https://github.com/StudioPlatforms/aistupidlevel-sdk/issues
+Author-email: AI Stupid Level <hello@aistupidlevel.info>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aistupidlevel,langchain,llm,model-routing,openai-compatible,router
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: langchain-core<2,>=1.0
+Requires-Dist: langchain-openai<2,>=1.0
+Provides-Extra: test
+Requires-Dist: langchain-tests<2,>=1.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest-socket>=0.7; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# langchain-aistupidlevel
+
+A LangChain chat model for the [AI Stupid Level](https://aistupidlevel.info/router) Smart Router.
+
+Instead of a fixed model you pick a routing mode, such as `auto-coding`, `auto-reasoning`, `auto-tooling`, `auto-best` or `auto-value`. Each request goes to the model that scores best for that mode on AI Stupid Level's benchmarks, among the providers you connected (OpenAI, Anthropic, Google, DeepSeek, Kimi, GLM). The router calls that model with your own provider keys and adds nothing to token prices.
+
+## Install
+
+```sh
+pip install -U langchain-aistupidlevel
+export ASL_ROUTER_KEY="aism_..."   # https://aistupidlevel.info/router/keys
+```
+
+## Use
+
+```python
+from langchain_aistupidlevel import ChatAISL
+
+llm = ChatAISL(model="auto-coding")
+msg = llm.invoke("Write a Python function that reverses a string.")
+
+print(msg.content)
+print(msg.response_metadata["routed_model"])     # the model that answered, e.g. claude-opus-5-5
+print(msg.response_metadata["routed_provider"])  # e.g. anthropic
+print(msg.response_metadata["routing_reason"])   # why the router chose it
+```
+
+`ChatAISL` is built on `ChatOpenAI`, so tool calling (`bind_tools`), structured output (`with_structured_output`), streaming and async work the same way. A model id such as `claude-opus-5-5` instead of a routing mode pins that model.
+
+**What it adds over `ChatOpenAI` with a base URL:** the router reports which model answered and why in response headers, which `ChatOpenAI` drops. `ChatAISL` copies them into `response_metadata` as `routed_model`, `routed_provider`, `routing_reason`, `routing_latency_ms` and `routing_request_id`.
+
+### Sandbox
+
+```python
+llm = ChatAISL(model="auto-tooling", sandbox=True)
+```
+
+The routing is real and the answer is a mock: nothing is sent to a model or counted. It is useful for building and testing before you add provider keys.
+
+## Configuration
+
+| Parameter | Environment variable | Default |
+|---|---|---|
+| `api_key` | `ASL_ROUTER_KEY` | none |
+| `base_url` | `ASL_BASE_URL` | `https://aistupidlevel.info/v1` |
+| `model` | | `auto-best` |
+| `sandbox` | | `False` |
+
+The routing modes are described at https://aistupidlevel.info/router/docs#strategies. The router routes text and tool calls; image input is not supported.
+
+## Development
+
+```sh
+pip install -e ".[test]"
+pytest tests/unit_tests
+ASL_ROUTER_KEY=aism_... pytest tests/integration_tests            # sandbox: nothing spent
+ASL_ROUTER_KEY=aism_... ASL_LIVE=1 pytest tests/integration_tests # real models, with provider keys
+```
+
+MIT licence.

langchain_aistupidlevel-0.1.0/README.md

@@ -0,0 +1,60 @@
+# langchain-aistupidlevel
+
+A LangChain chat model for the [AI Stupid Level](https://aistupidlevel.info/router) Smart Router.
+
+Instead of a fixed model you pick a routing mode, such as `auto-coding`, `auto-reasoning`, `auto-tooling`, `auto-best` or `auto-value`. Each request goes to the model that scores best for that mode on AI Stupid Level's benchmarks, among the providers you connected (OpenAI, Anthropic, Google, DeepSeek, Kimi, GLM). The router calls that model with your own provider keys and adds nothing to token prices.
+
+## Install
+
+```sh
+pip install -U langchain-aistupidlevel
+export ASL_ROUTER_KEY="aism_..."   # https://aistupidlevel.info/router/keys
+```
+
+## Use
+
+```python
+from langchain_aistupidlevel import ChatAISL
+
+llm = ChatAISL(model="auto-coding")
+msg = llm.invoke("Write a Python function that reverses a string.")
+
+print(msg.content)
+print(msg.response_metadata["routed_model"])     # the model that answered, e.g. claude-opus-5-5
+print(msg.response_metadata["routed_provider"])  # e.g. anthropic
+print(msg.response_metadata["routing_reason"])   # why the router chose it
+```
+
+`ChatAISL` is built on `ChatOpenAI`, so tool calling (`bind_tools`), structured output (`with_structured_output`), streaming and async work the same way. A model id such as `claude-opus-5-5` instead of a routing mode pins that model.
+
+**What it adds over `ChatOpenAI` with a base URL:** the router reports which model answered and why in response headers, which `ChatOpenAI` drops. `ChatAISL` copies them into `response_metadata` as `routed_model`, `routed_provider`, `routing_reason`, `routing_latency_ms` and `routing_request_id`.
+
+### Sandbox
+
+```python
+llm = ChatAISL(model="auto-tooling", sandbox=True)
+```
+
+The routing is real and the answer is a mock: nothing is sent to a model or counted. It is useful for building and testing before you add provider keys.
+
+## Configuration
+
+| Parameter | Environment variable | Default |
+|---|---|---|
+| `api_key` | `ASL_ROUTER_KEY` | none |
+| `base_url` | `ASL_BASE_URL` | `https://aistupidlevel.info/v1` |
+| `model` | | `auto-best` |
+| `sandbox` | | `False` |
+
+The routing modes are described at https://aistupidlevel.info/router/docs#strategies. The router routes text and tool calls; image input is not supported.
+
+## Development
+
+```sh
+pip install -e ".[test]"
+pytest tests/unit_tests
+ASL_ROUTER_KEY=aism_... pytest tests/integration_tests            # sandbox: nothing spent
+ASL_ROUTER_KEY=aism_... ASL_LIVE=1 pytest tests/integration_tests # real models, with provider keys
+```
+
+MIT licence.

langchain_aistupidlevel-0.1.0/langchain_aistupidlevel/__init__.py

@@ -0,0 +1,6 @@
+"""LangChain integration for the AI Stupid Level Smart Router."""
+
+from langchain_aistupidlevel.chat_models import ChatAISL
+
+__all__ = ["ChatAISL"]
+__version__ = "0.1.0"

langchain_aistupidlevel-0.1.0/langchain_aistupidlevel/chat_models.py

@@ -0,0 +1,153 @@
+"""ChatAISL: the AI Stupid Level Smart Router as a LangChain chat model."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, AsyncIterator, Iterator
+
+from langchain_core.outputs import ChatGenerationChunk, ChatResult
+from langchain_openai.chat_models.base import BaseChatOpenAI
+from pydantic import Field, SecretStr, model_validator
+
+DEFAULT_BASE_URL = "https://aistupidlevel.info/v1"
+
+# Response headers that say which model answered and why, copied into response_metadata.
+_ROUTING_HEADERS = {
+    "x-aism-model": "routed_model",
+    "x-aism-provider": "routed_provider",
+    "x-aism-reasoning": "routing_reason",
+    "x-aism-latency": "routing_latency_ms",
+    "x-aism-request-id": "routing_request_id",
+}
+
+
+def _routing_metadata(headers: dict | None) -> dict:
+    """The routing facts from the router's response headers."""
+    if not headers:
+        return {}
+    lower = {str(k).lower(): v for k, v in headers.items()}
+    out = {name: lower[h] for h, name in _ROUTING_HEADERS.items() if lower.get(h)}
+    if "routing_latency_ms" in out:
+        try:
+            out["routing_latency_ms"] = int(out["routing_latency_ms"])
+        except ValueError:
+            out.pop("routing_latency_ms")
+    if lower.get("x-aism-sandbox") == "true":
+        out["sandbox"] = True
+    return out
+
+
+class ChatAISL(BaseChatOpenAI):
+    """Chat model for the AI Stupid Level Smart Router.
+
+    Instead of a fixed model, pass a routing mode such as ``auto-coding``, ``auto-reasoning``,
+    ``auto-tooling``, ``auto-best`` or ``auto-value``. Each request goes to the model that scores
+    best for that mode on AI Stupid Level's benchmarks, among the providers you connected, and is
+    called with your own provider keys. A model id such as ``claude-opus-5-5`` pins that model.
+
+    Setup:
+        .. code-block:: bash
+
+            pip install -U langchain-aistupidlevel
+            export ASL_ROUTER_KEY="aism_..."   # https://aistupidlevel.info/router/keys
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_aistupidlevel import ChatAISL
+
+            llm = ChatAISL(model="auto-coding")
+
+    Invoke:
+        .. code-block:: python
+
+            msg = llm.invoke("Write a Python function that reverses a string.")
+            msg.content
+            msg.response_metadata["routed_model"]    # e.g. "claude-opus-5-5"
+            msg.response_metadata["routing_reason"]  # why the router chose it
+
+    Sandbox (real routing, mock answers, nothing spent or counted):
+        .. code-block:: python
+
+            llm = ChatAISL(model="auto-coding", sandbox=True)
+
+    Tool calling, structured output and streaming work as with ``ChatOpenAI``.
+    """
+
+    model_name: str = Field(default="auto-best", alias="model")
+    """A routing mode (``auto-coding``, ``auto-best``, …) or a model id to pin."""
+
+    openai_api_key: SecretStr | None = Field(
+        alias="api_key",
+        default_factory=lambda: SecretStr(os.environ["ASL_ROUTER_KEY"]) if os.environ.get("ASL_ROUTER_KEY") else None,
+    )
+    """Router key (``aism_…``). Read from ``ASL_ROUTER_KEY`` when not given."""
+
+    openai_api_base: str | None = Field(
+        alias="base_url",
+        default_factory=lambda: os.environ.get("ASL_BASE_URL") or DEFAULT_BASE_URL,
+    )
+    """Router endpoint. Read from ``ASL_BASE_URL`` when set."""
+
+    sandbox: bool = False
+    """Real routing with a mock answer: nothing is sent to a model or counted."""
+
+    stream_usage: bool | None = True
+    """Ask for token usage at the end of a stream, as ChatOpenAI does for OpenAI."""
+
+    include_response_headers: bool = True
+    """Kept on so the routing headers can be copied into ``response_metadata``."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _sandbox_header(cls, values: Any) -> Any:
+        if isinstance(values, dict) and values.get("sandbox"):
+            headers = dict(values.get("default_headers") or {})
+            headers["X-ASL-Sandbox"] = "true"
+            values["default_headers"] = headers
+        return values
+
+    @property
+    def _llm_type(self) -> str:
+        return "aistupidlevel-chat"
+
+    @property
+    def lc_secrets(self) -> dict[str, str]:
+        return {"openai_api_key": "ASL_ROUTER_KEY"}
+
+    @classmethod
+    def get_lc_namespace(cls) -> list[str]:
+        return ["langchain_aistupidlevel", "chat_models"]
+
+    @classmethod
+    def is_lc_serializable(cls) -> bool:
+        # langchain-core only revives classes it lists in its own mapping, so a
+        # serialized ChatAISL could not be loaded again.
+        return False
+
+    def _get_ls_params(self, stop: list[str] | None = None, **kwargs: Any) -> Any:
+        params = super()._get_ls_params(stop=stop, **kwargs)
+        params["ls_provider"] = "aistupidlevel"
+        return params
+
+    def _create_chat_result(self, response: Any, generation_info: dict | None = None) -> ChatResult:
+        result = super()._create_chat_result(response, generation_info)
+        routing = _routing_metadata((generation_info or {}).get("headers"))
+        if routing:
+            for gen in result.generations:
+                gen.message.response_metadata.update(routing)
+        return result
+
+    def _stream(self, *args: Any, **kwargs: Any) -> Iterator[ChatGenerationChunk]:
+        for chunk in super()._stream(*args, **kwargs):
+            routing = _routing_metadata((chunk.generation_info or {}).get("headers"))
+            if routing:
+                chunk.message.response_metadata.update(routing)
+            yield chunk
+
+    async def _astream(self, *args: Any, **kwargs: Any) -> AsyncIterator[ChatGenerationChunk]:
+        async for chunk in super()._astream(*args, **kwargs):
+            routing = _routing_metadata((chunk.generation_info or {}).get("headers"))
+            if routing:
+                chunk.message.response_metadata.update(routing)
+            yield chunk

langchain_aistupidlevel-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-aistupidlevel"
+version = "0.1.0"
+description = "LangChain chat model for the AI Stupid Level Smart Router: each request goes to the model that scores best for the task, with your own provider keys."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "AI Stupid Level", email = "hello@aistupidlevel.info" }]
+keywords = ["langchain", "llm", "router", "aistupidlevel", "openai-compatible", "model-routing"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = ["langchain-openai>=1.0,<2", "langchain-core>=1.0,<2"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23", "pytest-socket>=0.7", "langchain-tests>=1.0,<2"]
+
+[project.urls]
+Homepage = "https://aistupidlevel.info/router"
+Documentation = "https://aistupidlevel.info/router/docs#integrations"
+Source = "https://github.com/StudioPlatforms/aistupidlevel-sdk/tree/main/langchain-python"
+Issues = "https://github.com/StudioPlatforms/aistupidlevel-sdk/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["langchain_aistupidlevel"]
+
+[tool.hatch.build.targets.sdist]
+include = ["langchain_aistupidlevel", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "session"
+asyncio_default_test_loop_scope = "session"

langchain_aistupidlevel-0.1.0/tests/integration_tests/conftest.py

@@ -0,0 +1,13 @@
+import os
+
+import pytest
+
+SANDBOX_ONLY_FAILS = ("test_tool_calling", "test_tool_calling_async", "test_unicode_tool_call_integration")
+
+
+def pytest_collection_modifyitems(items):
+    if os.environ.get("ASL_LIVE") == "1":
+        return
+    for item in items:
+        if item.originalname in SANDBOX_ONLY_FAILS:
+            item.add_marker(pytest.mark.xfail(reason="sandbox answers use placeholder tool arguments", strict=True))

langchain_aistupidlevel-0.1.0/tests/integration_tests/test_chat_models.py

@@ -0,0 +1,48 @@
+"""Standard LangChain integration tests. Needs ASL_ROUTER_KEY.
+
+By default they run in sandbox mode: real routing, mock answers, nothing spent. A mock answer
+fills tool arguments with placeholders, so the tests that check the arguments' values are
+expected to fail there. Set ASL_LIVE=1 (with provider keys on the account) to run every test
+against real models."""
+
+import os
+
+import pytest
+from langchain_tests.integration_tests import ChatModelIntegrationTests
+
+from langchain_aistupidlevel import ChatAISL
+
+pytestmark = pytest.mark.skipif(not os.environ.get("ASL_ROUTER_KEY"), reason="ASL_ROUTER_KEY not set")
+
+LIVE = os.environ.get("ASL_LIVE") == "1"
+
+
+class TestChatAISLIntegration(ChatModelIntegrationTests):
+    @property
+    def chat_model_class(self) -> type[ChatAISL]:
+        return ChatAISL
+
+    @property
+    def chat_model_params(self) -> dict:
+        return {"model": "auto-tooling", "sandbox": not LIVE, "temperature": 0}
+
+    @property
+    def supports_image_inputs(self) -> bool:
+        return False  # the router routes text and tool calls only
+
+    @property
+    def returns_usage_metadata(self) -> bool:
+        return True
+
+
+def test_routing_metadata_on_invoke():
+    msg = ChatAISL(model="auto-coding", sandbox=True).invoke("Write a Python function that reverses a string.")
+    assert msg.response_metadata["routed_model"]
+    assert msg.response_metadata["routed_provider"]
+    assert msg.response_metadata["routing_reason"].startswith("Sandbox")
+    assert msg.response_metadata["sandbox"] is True
+
+
+def test_routing_metadata_on_stream():
+    chunks = list(ChatAISL(model="auto-coding", sandbox=True).stream("Say hi."))
+    assert any(c.response_metadata.get("routed_model") for c in chunks)

langchain_aistupidlevel-0.1.0/tests/unit_tests/test_chat_models.py

@@ -0,0 +1,49 @@
+"""Standard LangChain unit tests plus the routing metadata."""
+
+from langchain_tests.unit_tests import ChatModelUnitTests
+
+from langchain_aistupidlevel import ChatAISL
+from langchain_aistupidlevel.chat_models import _routing_metadata
+
+
+class TestChatAISLUnit(ChatModelUnitTests):
+    @property
+    def chat_model_class(self) -> type[ChatAISL]:
+        return ChatAISL
+
+    @property
+    def chat_model_params(self) -> dict:
+        return {"model": "auto-coding", "api_key": "aism_test"}
+
+    @property
+    def init_from_env_params(self) -> tuple[dict, dict, dict]:
+        return (
+            {"ASL_ROUTER_KEY": "aism_env", "ASL_BASE_URL": "https://example.test/v1"},
+            {"model": "auto-best"},
+            {"openai_api_key": "aism_env", "openai_api_base": "https://example.test/v1"},
+        )
+
+
+def test_defaults_point_at_the_router(monkeypatch):
+    monkeypatch.delenv("ASL_BASE_URL", raising=False)
+    llm = ChatAISL(api_key="aism_x")
+    assert llm.openai_api_base == "https://aistupidlevel.info/v1"
+    assert llm.model_name == "auto-best"
+    assert llm.include_response_headers is True
+
+
+def test_sandbox_sets_the_header():
+    llm = ChatAISL(api_key="aism_x", sandbox=True, default_headers={"X-Other": "1"})
+    assert llm.default_headers == {"X-Other": "1", "X-ASL-Sandbox": "true"}
+    assert ChatAISL(api_key="aism_x").default_headers is None
+
+
+def test_routing_metadata_from_headers():
+    meta = _routing_metadata({
+        "X-AISM-Model": "claude-opus-5-5", "x-aism-provider": "anthropic",
+        "x-aism-reasoning": "Ranked #1", "x-aism-latency": "1420", "x-aism-sandbox": "true",
+        "content-type": "application/json",
+    })
+    assert meta == {"routed_model": "claude-opus-5-5", "routed_provider": "anthropic",
+                    "routing_reason": "Ranked #1", "routing_latency_ms": 1420, "sandbox": True}
+    assert _routing_metadata(None) == {}