langchain-arcnm 0.1.0__tar.gz

langchain_arcnm-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+.DS_Store

langchain_arcnm-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+First release. Price a part from a CAD file or a part revision, read and list
+calculations, read the cost sheet at any lot size, find parts and their
+revisions, list costing environments, check the calculation allowance, and
+cancel a running calculation.

langchain_arcnm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rattle mng GmbH
+
+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_arcnm-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: langchain-arcnm
+Version: 0.1.0
+Summary: LangChain tools for ARCNM: manufacturing should-cost for machined and sheet-metal parts, from a CAD file.
+Project-URL: Homepage, https://arcnm.io
+Project-URL: Documentation, https://github.com/arcnm/langchain-arcnm#readme
+Project-URL: Source, https://github.com/arcnm/langchain-arcnm
+Project-URL: Changelog, https://github.com/arcnm/langchain-arcnm/blob/main/CHANGELOG.md
+Author-email: ARCNM <hello@arcnm.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arcnm,cad,langchain,manufacturing,quoting,should-cost
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: langchain-core<2.0.0,>=1.0.0
+Description-Content-Type: text/markdown
+
+# langchain-arcnm
+
+**Manufacturing should-cost from a CAD file, for your LangChain agent.**
+
+[ARCNM](https://arcnm.io) turns a STEP file into an itemised manufacturing cost
+for machined and sheet-metal parts: unit cost, setup cost, cycle time, and the
+cost sheet behind them. This package gives a LangChain or LangGraph agent the
+ARCNM REST API as tools, so it can price a part, explain what drives the cost,
+and compare lot sizes.
+
+```bash
+pip install -U langchain-arcnm
+```
+
+## Setup
+
+1. In ARCNM, open Settings, then API keys, then New key. ARCNM shows the key once.
+2. Export it:
+
+```bash
+export ARCNM_API_KEY="..."
+```
+
+Reads need the `parts:read` scope. Starting or cancelling a calculation needs
+`parts:write`. The Free plan includes 10 calculations a month, no card required.
+
+## Use it in an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_arcnm import ArcnmToolkit
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=ArcnmToolkit(root_dir="./cad").get_tools(),
+)
+result = agent.invoke(
+    {
+        "messages": [
+            {
+                "role": "user",
+                "content": "What does bracket.step cost at a lot of 50, and what drives it?",
+            }
+        ]
+    }
+)
+print(result["messages"][-1].content)
+```
+
+## Call a tool directly
+
+```python
+from langchain_arcnm import UploadAndQuoteTool
+
+quote = UploadAndQuoteTool()
+print(quote.invoke({"file_path": "bracket.step", "lot_size": 50}))
+```
+
+Every tool returns JSON as a string. An API error comes back as the tool
+result, with its stable error code and request id, so the agent can react to
+it; set `handle_tool_error=False` to have it raised instead.
+
+## Tools
+
+| Tool | What it does | Uses a calculation |
+|---|---|---|
+| `upload_and_quote` | Uploads a CAD file, and a drawing if you have one, and prices it. | Yes |
+| `quote_part` | Prices a part revision ARCNM already has, at another lot size or in another costing environment. | Yes |
+| `cancel_calculation` | Stops a calculation that is still queued or running. | No |
+| `get_calculation` | Reads one calculation: status, costs, cycle time, confidence. `wait=true` waits for it to finish. | No |
+| `list_calculations` | Lists recent calculations, by status or part. | No |
+| `get_cost_sheet` | The itemised cost sheet, at the priced lot size or any other. | No |
+| `list_parts` | Finds parts by part number. | No |
+| `list_part_revisions` | Lists a part's revisions, for `quote_part`. | No |
+| `list_environments` | Lists the costing environments (machines, rates, materials) a calculation can price with. | No |
+| `check_quota` | How many calculations are left in this period. | No |
+
+The names match the [ARCNM MCP server](https://github.com/arcnm/arcnm-mcp), so
+an agent sees the same verbs on either surface.
+
+`upload_and_quote`, `quote_part` and `get_calculation` with `wait=true` wait up
+to `wait_timeout` seconds (default 120) for the result. A calculation still
+running after that comes back with its id, and the agent can ask again with
+`get_calculation`.
+
+## Configuration
+
+Pass these to `ArcnmToolkit` or to any single tool.
+
+| Argument | Default | |
+|---|---|---|
+| `api_key` | `ARCNM_API_KEY` | Your ARCNM API key. |
+| `base_url` | `ARCNM_BASE_URL`, else `https://api.arcnm.io` | Change it only when you were given a different origin. |
+| `org_slug` | `ARCNM_ORG_SLUG` | The organization to act in, for a key that belongs to several. |
+| `root_dir` | none | The directory `upload_and_quote` may read files from. |
+| `read_only` | `False` | Toolkit only. Leaves out the tools that start or stop a calculation. |
+| `wait_timeout` | `120` | Seconds to wait for a started calculation. `0` returns at once. |
+| `poll_interval` | `2` | Seconds between status checks while waiting. |
+| `request_timeout` | `60` | Seconds one HTTP request may take. |
+
+## Security
+
+`upload_and_quote` reads the file path the model gives it and sends that file
+to ARCNM. Set `root_dir` so it can only read the folder you meant, and use
+`read_only=True` for an agent that should never start a calculation. A key with
+only `parts:read` cannot start one either.
+
+## Development
+
+```bash
+uv sync --all-groups
+make test              # unit tests, no network
+make integration_test  # against the live API; needs ARCNM_API_KEY, uses no calculations
+make lint
+```
+
+`make integration_test BILLABLE=1` also quotes `tests/integration_tests/shaft_thread.step`,
+which uses one calculation.
+
+`arcnm-contract.json` lists every ARCNM operation and field this package relies
+on. ARCNM checks it against every change to its API before that change merges.
+It is not part of the published package.
+
+## Links
+
+* [ARCNM docs](https://arcnm.io/docs)
+* [ARCNM API examples](https://github.com/arcnm/arcnm-examples)
+* [LangChain tools](https://docs.langchain.com/oss/python/langchain/tools)
+
+## License
+
+MIT

langchain_arcnm-0.1.0/README.md

@@ -0,0 +1,132 @@
+# langchain-arcnm
+
+**Manufacturing should-cost from a CAD file, for your LangChain agent.**
+
+[ARCNM](https://arcnm.io) turns a STEP file into an itemised manufacturing cost
+for machined and sheet-metal parts: unit cost, setup cost, cycle time, and the
+cost sheet behind them. This package gives a LangChain or LangGraph agent the
+ARCNM REST API as tools, so it can price a part, explain what drives the cost,
+and compare lot sizes.
+
+```bash
+pip install -U langchain-arcnm
+```
+
+## Setup
+
+1. In ARCNM, open Settings, then API keys, then New key. ARCNM shows the key once.
+2. Export it:
+
+```bash
+export ARCNM_API_KEY="..."
+```
+
+Reads need the `parts:read` scope. Starting or cancelling a calculation needs
+`parts:write`. The Free plan includes 10 calculations a month, no card required.
+
+## Use it in an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_arcnm import ArcnmToolkit
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=ArcnmToolkit(root_dir="./cad").get_tools(),
+)
+result = agent.invoke(
+    {
+        "messages": [
+            {
+                "role": "user",
+                "content": "What does bracket.step cost at a lot of 50, and what drives it?",
+            }
+        ]
+    }
+)
+print(result["messages"][-1].content)
+```
+
+## Call a tool directly
+
+```python
+from langchain_arcnm import UploadAndQuoteTool
+
+quote = UploadAndQuoteTool()
+print(quote.invoke({"file_path": "bracket.step", "lot_size": 50}))
+```
+
+Every tool returns JSON as a string. An API error comes back as the tool
+result, with its stable error code and request id, so the agent can react to
+it; set `handle_tool_error=False` to have it raised instead.
+
+## Tools
+
+| Tool | What it does | Uses a calculation |
+|---|---|---|
+| `upload_and_quote` | Uploads a CAD file, and a drawing if you have one, and prices it. | Yes |
+| `quote_part` | Prices a part revision ARCNM already has, at another lot size or in another costing environment. | Yes |
+| `cancel_calculation` | Stops a calculation that is still queued or running. | No |
+| `get_calculation` | Reads one calculation: status, costs, cycle time, confidence. `wait=true` waits for it to finish. | No |
+| `list_calculations` | Lists recent calculations, by status or part. | No |
+| `get_cost_sheet` | The itemised cost sheet, at the priced lot size or any other. | No |
+| `list_parts` | Finds parts by part number. | No |
+| `list_part_revisions` | Lists a part's revisions, for `quote_part`. | No |
+| `list_environments` | Lists the costing environments (machines, rates, materials) a calculation can price with. | No |
+| `check_quota` | How many calculations are left in this period. | No |
+
+The names match the [ARCNM MCP server](https://github.com/arcnm/arcnm-mcp), so
+an agent sees the same verbs on either surface.
+
+`upload_and_quote`, `quote_part` and `get_calculation` with `wait=true` wait up
+to `wait_timeout` seconds (default 120) for the result. A calculation still
+running after that comes back with its id, and the agent can ask again with
+`get_calculation`.
+
+## Configuration
+
+Pass these to `ArcnmToolkit` or to any single tool.
+
+| Argument | Default | |
+|---|---|---|
+| `api_key` | `ARCNM_API_KEY` | Your ARCNM API key. |
+| `base_url` | `ARCNM_BASE_URL`, else `https://api.arcnm.io` | Change it only when you were given a different origin. |
+| `org_slug` | `ARCNM_ORG_SLUG` | The organization to act in, for a key that belongs to several. |
+| `root_dir` | none | The directory `upload_and_quote` may read files from. |
+| `read_only` | `False` | Toolkit only. Leaves out the tools that start or stop a calculation. |
+| `wait_timeout` | `120` | Seconds to wait for a started calculation. `0` returns at once. |
+| `poll_interval` | `2` | Seconds between status checks while waiting. |
+| `request_timeout` | `60` | Seconds one HTTP request may take. |
+
+## Security
+
+`upload_and_quote` reads the file path the model gives it and sends that file
+to ARCNM. Set `root_dir` so it can only read the folder you meant, and use
+`read_only=True` for an agent that should never start a calculation. A key with
+only `parts:read` cannot start one either.
+
+## Development
+
+```bash
+uv sync --all-groups
+make test              # unit tests, no network
+make integration_test  # against the live API; needs ARCNM_API_KEY, uses no calculations
+make lint
+```
+
+`make integration_test BILLABLE=1` also quotes `tests/integration_tests/shaft_thread.step`,
+which uses one calculation.
+
+`arcnm-contract.json` lists every ARCNM operation and field this package relies
+on. ARCNM checks it against every change to its API before that change merges.
+It is not part of the published package.
+
+## Links
+
+* [ARCNM docs](https://arcnm.io/docs)
+* [ARCNM API examples](https://github.com/arcnm/arcnm-examples)
+* [LangChain tools](https://docs.langchain.com/oss/python/langchain/tools)
+
+## License
+
+MIT

langchain_arcnm-0.1.0/langchain_arcnm/__init__.py

@@ -0,0 +1,34 @@
+"""LangChain tools for ARCNM: manufacturing should-cost from a CAD file."""
+
+from langchain_arcnm._client import ArcnmAPIError, ArcnmClient
+from langchain_arcnm.toolkit import ArcnmToolkit
+from langchain_arcnm.tools import (
+    ArcnmBaseTool,
+    CancelCalculationTool,
+    CheckQuotaTool,
+    GetCalculationTool,
+    GetCostSheetTool,
+    ListCalculationsTool,
+    ListEnvironmentsTool,
+    ListPartRevisionsTool,
+    ListPartsTool,
+    QuotePartTool,
+    UploadAndQuoteTool,
+)
+
+__all__ = [
+    "ArcnmAPIError",
+    "ArcnmBaseTool",
+    "ArcnmClient",
+    "ArcnmToolkit",
+    "CancelCalculationTool",
+    "CheckQuotaTool",
+    "GetCalculationTool",
+    "GetCostSheetTool",
+    "ListCalculationsTool",
+    "ListEnvironmentsTool",
+    "ListPartRevisionsTool",
+    "ListPartsTool",
+    "QuotePartTool",
+    "UploadAndQuoteTool",
+]

langchain_arcnm-0.1.0/langchain_arcnm/_client.py

@@ -0,0 +1,244 @@
+"""HTTP calls to the ARCNM REST API. One small client, no LangChain imports."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import IO, Any
+
+import httpx
+
+DEFAULT_BASE_URL = "https://api.arcnm.io"
+API_PREFIX = "/api/v1"
+USER_AGENT = "langchain-arcnm/0.1.0"
+
+#: A calculation in one of these states will not change on its own. ``blocked``
+#: means it was created but parked because the plan has no calculations left.
+TERMINAL_STATUSES = frozenset({"succeeded", "failed", "cancelled", "timed_out", "blocked"})
+
+
+class ArcnmAPIError(Exception):
+    """An ARCNM API call failed.
+
+    ``code`` is the stable ``error.code`` of the response; branch on it, never
+    on the message. ``request_id`` is what ARCNM support asks for.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+
+
+def normalize_base_url(value: str) -> str:
+    """The API origin, without a trailing slash or the ``/api/v1`` prefix."""
+    url = httpx.URL(value.strip())
+    if url.scheme not in ("http", "https") or not url.host:
+        raise ValueError("The ARCNM base URL must start with http:// or https://.")
+    if url.userinfo:
+        raise ValueError("Pass the API key as api_key, not inside the base URL.")
+    origin = str(url.copy_with(path="/", query=None, fragment=None)).rstrip("/")
+    return origin
+
+
+def _failure(response: httpx.Response) -> ArcnmAPIError:
+    body: Any = None
+    if response.headers.get("content-type", "").startswith("application/json"):
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+    envelope = body.get("error") if isinstance(body, dict) else None
+    code = envelope.get("code") if isinstance(envelope, dict) else None
+    message = envelope.get("message") if isinstance(envelope, dict) else None
+    if message is None and isinstance(body, dict) and isinstance(body.get("detail"), str):
+        message = body["detail"]
+    request_id = body.get("request_id") if isinstance(body, dict) else None
+    text = message or response.reason_phrase or "request failed"
+    if code:
+        text = f"{code}: {text}"
+    if request_id:
+        text = f"{text} (request_id {request_id})"
+    return ArcnmAPIError(
+        f"ARCNM returned HTTP {response.status_code}. {text}",
+        status_code=response.status_code,
+        code=code if isinstance(code, str) else None,
+        request_id=request_id if isinstance(request_id, str) else None,
+    )
+
+
+class ArcnmClient:
+    """A thin, synchronous client for the endpoints the tools call."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        org_slug: str | None = None,
+        timeout: float = 60.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError(
+                "No ARCNM API key. Set ARCNM_API_KEY, or pass api_key. "
+                "Create one in ARCNM under Settings, then API keys."
+            )
+        headers = {"X-API-Key": api_key, "Accept": "application/json", "User-Agent": USER_AGENT}
+        if org_slug:
+            headers["X-Org-Slug"] = org_slug
+        self._http = httpx.Client(
+            base_url=normalize_base_url(base_url) + API_PREFIX,
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def __enter__(self) -> ArcnmClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, tuple[str, IO[bytes]]] | None = None,
+    ) -> Any:
+        query = {k: v for k, v in (params or {}).items() if v is not None}
+        form = {k: str(v) for k, v in (data or {}).items() if v is not None}
+        try:
+            response = self._http.request(
+                method, path, params=query, json=json, data=form or None, files=files
+            )
+        except httpx.HTTPError as error:
+            raise ArcnmAPIError(f"Could not reach ARCNM: {error}") from error
+        if response.is_error:
+            raise _failure(response)
+        if not response.content:
+            return {}
+        return response.json()
+
+    # -- the calls ---------------------------------------------------------
+
+    def upload_and_quote(
+        self,
+        cad_path: Path,
+        *,
+        part_number: str,
+        drawing_path: Path | None = None,
+        lot_size: int | None = None,
+        annual_volume: int | None = None,
+        costing_environment_id: str | None = None,
+    ) -> dict[str, Any]:
+        fields = {
+            "part_number": part_number,
+            "lot_size": lot_size,
+            "annual_volume": annual_volume,
+            "costing_environment_id": costing_environment_id,
+        }
+        with cad_path.open("rb") as cad:
+            files: dict[str, tuple[str, IO[bytes]]] = {"cad_file": (cad_path.name, cad)}
+            if drawing_path is None:
+                return self.request(  # type: ignore[no-any-return]
+                    "POST", "/calculations/upload-and-quote", data=fields, files=files
+                )
+            with drawing_path.open("rb") as drawing:
+                files["drawing_file"] = (drawing_path.name, drawing)
+                return self.request(  # type: ignore[no-any-return]
+                    "POST", "/calculations/upload-and-quote", data=fields, files=files
+                )
+
+    def quote(
+        self,
+        part_revision_id: str,
+        *,
+        lot_size: int | None = None,
+        annual_volume: int | None = None,
+        costing_environment_id: str | None = None,
+    ) -> dict[str, Any]:
+        body = {
+            "part_revision_id": part_revision_id,
+            "lot_size": lot_size,
+            "annual_volume": annual_volume,
+            "costing_environment_id": costing_environment_id,
+        }
+        return self.request(  # type: ignore[no-any-return]
+            "POST", "/calculations/quote", json={k: v for k, v in body.items() if v is not None}
+        )
+
+    def get_calculation(self, calculation_id: str) -> dict[str, Any]:
+        return self.request(  # type: ignore[no-any-return]
+            "GET",
+            f"/calculations/{calculation_id}",
+            params={"include_analytics": "false"},
+        )
+
+    def wait_for_calculation(
+        self, calculation: dict[str, Any], *, timeout: float, poll_interval: float
+    ) -> dict[str, Any]:
+        """Poll until the calculation is terminal or ``timeout`` seconds pass."""
+        deadline = time.monotonic() + timeout
+        while not is_terminal(calculation) and time.monotonic() < deadline:
+            time.sleep(min(poll_interval, max(0.0, deadline - time.monotonic())))
+            calculation = self.get_calculation(str(calculation["id"]))
+        return calculation
+
+    def list_calculations(
+        self, *, status: str | None = None, part_id: str | None = None, limit: int = 10
+    ) -> dict[str, Any]:
+        return self.request(  # type: ignore[no-any-return]
+            "GET",
+            "/calculations",
+            params={"status_filter": status, "part_id": part_id, "limit": limit},
+        )
+
+    def get_cost_sheet(self, calculation_id: str, *, quantity: int | None = None) -> dict[str, Any]:
+        return self.request(  # type: ignore[no-any-return]
+            "GET", f"/calculations/{calculation_id}/cost-sheet", params={"quantity": quantity}
+        )
+
+    def cancel_calculation(self, calculation_id: str) -> dict[str, Any]:
+        return self.request(  # type: ignore[no-any-return]
+            "POST", f"/calculations/{calculation_id}/cancel"
+        )
+
+    def list_environments(self, *, limit: int = 20) -> list[dict[str, Any]]:
+        return self.request(  # type: ignore[no-any-return]
+            "GET", "/environments/", params={"limit": limit}
+        )
+
+    def get_entitlement(self) -> dict[str, Any]:
+        return self.request("GET", "/calculations/entitlement")  # type: ignore[no-any-return]
+
+    def list_parts(self, *, query: str | None = None, limit: int = 10) -> dict[str, Any]:
+        return self.request(  # type: ignore[no-any-return]
+            "GET", "/parts/", params={"q": query, "limit": limit}
+        )
+
+    def list_part_revisions(self, part_id: str, *, limit: int = 10) -> dict[str, Any]:
+        return self.request(  # type: ignore[no-any-return]
+            "GET", f"/parts/{part_id}/revisions", params={"limit": limit, "order": "desc"}
+        )
+
+
+def is_terminal(calculation: dict[str, Any]) -> bool:
+    if calculation.get("terminal") is True:
+        return True
+    return calculation.get("status") in TERMINAL_STATUSES