arugulanet 0.1.0__tar.gz

arugulanet-0.1.0/LICENSE

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

arugulanet-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: arugulanet
+Version: 0.1.0
+Summary: Find offers that fit a request through Arugula, with LangChain, LangGraph and CrewAI tools.
+License: MIT
+Project-URL: Homepage, https://arugulanet.com
+Keywords: arugulanet,offers,langchain,langgraph,crewai,agents,tools
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.3; extra == "langgraph"
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80; extra == "crewai"
+Dynamic: license-file
+
+# arugulanet
+
+Find offers that fit a request through Arugula, for Python agents. It uses an anonymous session, so
+no account is needed. Every offer comes with a tracked link the user follows to buy. The core has no
+dependencies.
+
+Arugula is a matching engine: offers are ranked by fit only. The tools return a `disclosure` with the
+offers; show it to the user with them: "Ranked by fit only. Arugula may earn a commission if you buy through these links, at no extra cost to you."
+
+```python
+from arugulanet import Arugula
+
+offers = Arugula().find_offers("a hotel room in Singapore for two nights", party_size=2)
+```
+
+## LangChain and LangGraph
+
+Install with `pip install "arugulanet[langchain]"`, or `"arugulanet[langgraph]"`. The tool sends channel
+`langchain`.
+
+```python
+from arugulanet.langchain import find_offers_tool
+
+tools = [find_offers_tool()]  # also for LangGraph: create_react_agent(model, tools)
+```
+
+## CrewAI
+
+Install with `pip install "arugulanet[crewai]"`. The tool sends channel `crewai`.
+
+```python
+from arugulanet.crewai import FindOffersTool
+
+agent = Agent(role="Shopper", goal="Find what the user needs", backstory="...", tools=[FindOffersTool()])
+```
+
+## More
+
+- **Example:** `python examples/agent.py "your request"`. Set `ARUGULA_API_URL` to use another API.
+- **Build:** `python -m build`.
+- **Publish:** `twine upload dist/*`, with the PyPI organization account.

arugulanet-0.1.0/README.md

@@ -0,0 +1,41 @@
+# arugulanet
+
+Find offers that fit a request through Arugula, for Python agents. It uses an anonymous session, so
+no account is needed. Every offer comes with a tracked link the user follows to buy. The core has no
+dependencies.
+
+Arugula is a matching engine: offers are ranked by fit only. The tools return a `disclosure` with the
+offers; show it to the user with them: "Ranked by fit only. Arugula may earn a commission if you buy through these links, at no extra cost to you."
+
+```python
+from arugulanet import Arugula
+
+offers = Arugula().find_offers("a hotel room in Singapore for two nights", party_size=2)
+```
+
+## LangChain and LangGraph
+
+Install with `pip install "arugulanet[langchain]"`, or `"arugulanet[langgraph]"`. The tool sends channel
+`langchain`.
+
+```python
+from arugulanet.langchain import find_offers_tool
+
+tools = [find_offers_tool()]  # also for LangGraph: create_react_agent(model, tools)
+```
+
+## CrewAI
+
+Install with `pip install "arugulanet[crewai]"`. The tool sends channel `crewai`.
+
+```python
+from arugulanet.crewai import FindOffersTool
+
+agent = Agent(role="Shopper", goal="Find what the user needs", backstory="...", tools=[FindOffersTool()])
+```
+
+## More
+
+- **Example:** `python examples/agent.py "your request"`. Set `ARUGULA_API_URL` to use another API.
+- **Build:** `python -m build`.
+- **Publish:** `twine upload dist/*`, with the PyPI organization account.

arugulanet-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "arugulanet"
+version = "0.1.0"
+description = "Find offers that fit a request through Arugula, with LangChain, LangGraph and CrewAI tools."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["arugulanet", "offers", "langchain", "langgraph", "crewai", "agents", "tools"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3"]
+langgraph = ["langchain-core>=0.3", "langgraph>=0.2"]
+crewai = ["crewai>=0.80"]
+
+[project.urls]
+Homepage = "https://arugulanet.com"
+
+[tool.setuptools.packages.find]
+where = ["src"]

arugulanet-0.1.0/setup.cfg

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

arugulanet-0.1.0/src/arugulanet/__init__.py

@@ -0,0 +1,11 @@
+"""Arugula for Python agents: find offers that fit a request, with LangChain, LangGraph and CrewAI tools.
+
+    from arugulanet import Arugula
+    offers = Arugula().find_offers("a hotel room in Singapore for two nights", party_size=2)
+"""
+
+from .client import Arugula, ArugulaError
+from .tools import DISCLOSURE, FIND_OFFERS_DESCRIPTION, FIND_OFFERS_SCHEMA, run_find_offers
+
+__all__ = ["Arugula", "ArugulaError", "DISCLOSURE", "FIND_OFFERS_DESCRIPTION", "FIND_OFFERS_SCHEMA", "run_find_offers"]
+__version__ = "0.1.0"

arugulanet-0.1.0/src/arugulanet/client.py

@@ -0,0 +1,91 @@
+"""A small client for Arugula's public API, on the standard library only.
+
+There is no generated Python client yet, so this calls the four public operations it needs by hand:
+start an anonymous session, mint a request, declare it, and read its ranked offers. Responses are
+returned as the API's JSON (dicts), following the API contract (backend api/openapi.yaml).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Dict, List, Optional
+
+DEFAULT_API = "https://api.arugulanet.com"
+
+
+class ArugulaError(Exception):
+    """An API error, with its HTTP status and the server's message."""
+
+    def __init__(self, status: int, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class Arugula:
+    """One anonymous session on Arugula's public API, started on first use and renewed when refused."""
+
+    def __init__(self, base_url: str = DEFAULT_API, channel: str = "langchain", timeout: float = 30.0) -> None:
+        base = base_url.rstrip("/")
+        self.base_url = base[: -len("/v1")] if base.endswith("/v1") else base
+        self.channel = channel
+        self.timeout = timeout
+        self._token: Optional[str] = None
+
+    def _call(self, method: str, path: str, body: Optional[Dict[str, Any]] = None, auth: bool = True) -> Dict[str, Any]:
+        headers = {"Content-Type": "application/json", "Accept": "application/json"}
+        if auth:
+            headers["Authorization"] = "Bearer " + self._session()
+        if method == "POST" and path != "/v1/public/sessions":
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+        data = json.dumps(body).encode() if body is not None else None
+        request = urllib.request.Request(self.base_url + path, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                text = response.read().decode()
+                return json.loads(text) if text else {}
+        except urllib.error.HTTPError as error:
+            text = error.read().decode(errors="replace")
+            try:
+                problem = json.loads(text)
+                message = problem.get("detail") or problem.get("title") or text
+            except ValueError:
+                message = text or str(error)
+            raise ArugulaError(error.code, message) from None
+
+    def _session(self) -> str:
+        if self._token is None:
+            session = self._call("POST", "/v1/public/sessions", {"channel": self.channel}, auth=False)
+            self._token = session["session_token"]
+        return self._token
+
+    def _authorized(self, method: str, path: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        try:
+            return self._call(method, path, body)
+        except ArugulaError as error:
+            if error.status != 401:
+                raise
+            self._token = None
+            return self._call(method, path, body)
+
+    def find_offers(self, request: str, *, wait: float = 30.0, limit: int = 5, **stated: Any) -> List[Dict[str, Any]]:
+        """The offers that fit a request, best first; empty when it is too vague to act on or nothing fits.
+
+        Keyword arguments are the stated context: location, dates, budget ({"amount", "currency"}),
+        party_size, preferences.
+        """
+        context = {key: value for key, value in stated.items() if value not in (None, "")}
+        minted = self._authorized("POST", "/v1/intents:mint", {"text": request, **({"stated": context} if context else {})})
+        draft = minted["draft"]
+        if draft["entailment"]["status"] != "passed":
+            return []
+        declared = self._authorized("POST", "/v1/intents", {"draft_id": draft["intent_id"]})
+        deadline = time.monotonic() + wait
+        while True:
+            ranked = self._authorized("GET", "/v1/intents/" + declared["demand_id"] + "/offers")
+            if ranked.get("run_id") is not None or ranked.get("data") or time.monotonic() > deadline:
+                return sorted(ranked.get("data", []), key=lambda offer: offer.get("rank", 0))[:limit]
+            time.sleep(1.5)

arugulanet-0.1.0/src/arugulanet/crewai.py

@@ -0,0 +1,46 @@
+"""CrewAI tool: pip install "arugulanet[crewai]".
+
+    from arugulanet.crewai import FindOffersTool
+    agent = Agent(role="Shopper", goal="...", backstory="...", tools=[FindOffersTool()])
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Type
+
+from crewai.tools import BaseTool
+from pydantic import BaseModel, Field, PrivateAttr
+
+from .client import Arugula
+from .tools import FIND_OFFERS_DESCRIPTION, run_find_offers
+
+
+class FindOffersInput(BaseModel):
+    request: str = Field(description="What the user needs, in their own words.")
+    location: Optional[str] = Field(default=None, description="Where, if the user said.")
+    dates: Optional[str] = Field(default=None, description="When, if the user said.")
+    budget_amount: Optional[float] = Field(default=None, description="The user's budget, if they said.")
+    budget_currency: Optional[str] = Field(default=None, description="ISO 4217 currency of the budget.")
+    party_size: Optional[int] = Field(default=None, description="How many people, if relevant.")
+    preferences: Optional[str] = Field(default=None, description="Anything else the user prefers.")
+
+
+class FindOffersTool(BaseTool):
+    """The find_offers tool on channel crewai."""
+
+    name: str = "find_offers"
+    description: str = FIND_OFFERS_DESCRIPTION
+    args_schema: Type[BaseModel] = FindOffersInput
+    _client: Arugula = PrivateAttr(default_factory=lambda: Arugula(channel="crewai"))
+
+    def _run(
+        self,
+        request: str,
+        location: Optional[str] = None,
+        dates: Optional[str] = None,
+        budget_amount: Optional[float] = None,
+        budget_currency: Optional[str] = None,
+        party_size: Optional[int] = None,
+        preferences: Optional[str] = None,
+    ) -> str:
+        return run_find_offers(self._client, request, location, dates, budget_amount, budget_currency, party_size, preferences)

arugulanet-0.1.0/src/arugulanet/langchain.py

@@ -0,0 +1,34 @@
+"""LangChain (and LangGraph) tool: pip install "arugulanet[langchain]".
+
+    from arugulanet.langchain import find_offers_tool
+    tools = [find_offers_tool()]
+
+LangGraph agents take the same tool, for example create_react_agent(model, [find_offers_tool()]).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from langchain_core.tools import StructuredTool
+
+from .client import Arugula
+from .tools import FIND_OFFERS_DESCRIPTION, run_find_offers
+
+
+def find_offers_tool(client: Optional[Arugula] = None) -> StructuredTool:
+    """The find_offers tool on channel langchain."""
+    agent = client or Arugula(channel="langchain")
+
+    def find_offers(
+        request: str,
+        location: Optional[str] = None,
+        dates: Optional[str] = None,
+        budget_amount: Optional[float] = None,
+        budget_currency: Optional[str] = None,
+        party_size: Optional[int] = None,
+        preferences: Optional[str] = None,
+    ) -> str:
+        return run_find_offers(agent, request, location, dates, budget_amount, budget_currency, party_size, preferences)
+
+    return StructuredTool.from_function(func=find_offers, name="find_offers", description=FIND_OFFERS_DESCRIPTION)

arugulanet-0.1.0/src/arugulanet/tools.py

@@ -0,0 +1,60 @@
+"""The find_offers tool, shared by the LangChain, LangGraph and CrewAI wrappers."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from .client import Arugula
+
+FIND_OFFERS_DESCRIPTION = (
+    "Find offers from sellers and listings that fit what the user needs, for example a product, a stay or a service. "
+    "Returns up to five offers ranked by fit, each with a title, a price when known, why it fits, and a link the user follows to buy, "
+    "plus a disclosure to show the user with them."
+)
+
+DISCLOSURE = "Ranked by fit only. Arugula may earn a commission if you buy through these links, at no extra cost to you."
+
+FIND_OFFERS_SCHEMA: Dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "request": {"type": "string", "description": "What the user needs, in their own words."},
+        "location": {"type": "string", "description": "Where, if the user said."},
+        "dates": {"type": "string", "description": "When, if the user said."},
+        "budget_amount": {"type": "number", "description": "The user's budget, if they said."},
+        "budget_currency": {"type": "string", "description": "ISO 4217 currency of the budget, for example SGD."},
+        "party_size": {"type": "integer", "description": "How many people, if relevant."},
+        "preferences": {"type": "string", "description": "Anything else the user prefers."},
+    },
+    "required": ["request"],
+}
+
+
+def run_find_offers(
+    client: Arugula,
+    request: str,
+    location: Optional[str] = None,
+    dates: Optional[str] = None,
+    budget_amount: Optional[float] = None,
+    budget_currency: Optional[str] = None,
+    party_size: Optional[int] = None,
+    preferences: Optional[str] = None,
+) -> str:
+    """Runs find_offers and returns the offers as compact JSON for a model."""
+    budget = {"amount": str(budget_amount), "currency": (budget_currency or "USD").upper()} if budget_amount is not None else None
+    offers = client.find_offers(request, location=location, dates=dates, budget=budget, party_size=party_size, preferences=preferences)
+    return json.dumps(
+        {
+            "disclosure": DISCLOSURE,
+            "offers": [
+            {
+                "title": offer.get("title") or offer.get("capability"),
+                "price": offer.get("price"),
+                "why": offer.get("rationale"),
+                "link": offer.get("tracked_url"),
+                "how_to_buy": offer.get("how_to_buy"),
+            }
+            for offer in offers
+            ],
+        }
+    )

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

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: arugulanet
+Version: 0.1.0
+Summary: Find offers that fit a request through Arugula, with LangChain, LangGraph and CrewAI tools.
+License: MIT
+Project-URL: Homepage, https://arugulanet.com
+Keywords: arugulanet,offers,langchain,langgraph,crewai,agents,tools
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.3; extra == "langgraph"
+Requires-Dist: langgraph>=0.2; extra == "langgraph"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80; extra == "crewai"
+Dynamic: license-file
+
+# arugulanet
+
+Find offers that fit a request through Arugula, for Python agents. It uses an anonymous session, so
+no account is needed. Every offer comes with a tracked link the user follows to buy. The core has no
+dependencies.
+
+Arugula is a matching engine: offers are ranked by fit only. The tools return a `disclosure` with the
+offers; show it to the user with them: "Ranked by fit only. Arugula may earn a commission if you buy through these links, at no extra cost to you."
+
+```python
+from arugulanet import Arugula
+
+offers = Arugula().find_offers("a hotel room in Singapore for two nights", party_size=2)
+```
+
+## LangChain and LangGraph
+
+Install with `pip install "arugulanet[langchain]"`, or `"arugulanet[langgraph]"`. The tool sends channel
+`langchain`.
+
+```python
+from arugulanet.langchain import find_offers_tool
+
+tools = [find_offers_tool()]  # also for LangGraph: create_react_agent(model, tools)
+```
+
+## CrewAI
+
+Install with `pip install "arugulanet[crewai]"`. The tool sends channel `crewai`.
+
+```python
+from arugulanet.crewai import FindOffersTool
+
+agent = Agent(role="Shopper", goal="Find what the user needs", backstory="...", tools=[FindOffersTool()])
+```
+
+## More
+
+- **Example:** `python examples/agent.py "your request"`. Set `ARUGULA_API_URL` to use another API.
+- **Build:** `python -m build`.
+- **Publish:** `twine upload dist/*`, with the PyPI organization account.

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

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+src/arugulanet/__init__.py
+src/arugulanet/client.py
+src/arugulanet/crewai.py
+src/arugulanet/langchain.py
+src/arugulanet/tools.py
+src/arugulanet.egg-info/PKG-INFO
+src/arugulanet.egg-info/SOURCES.txt
+src/arugulanet.egg-info/dependency_links.txt
+src/arugulanet.egg-info/requires.txt
+src/arugulanet.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,10 @@
+
+[crewai]
+crewai>=0.80
+
+[langchain]
+langchain-core>=0.3
+
+[langgraph]
+langchain-core>=0.3
+langgraph>=0.2

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

@@ -0,0 +1 @@
+arugulanet