actuent 0.2.0__py3-none-any.whl

actuent/__init__.py

@@ -0,0 +1,207 @@
+"""Actuent — the search engine for AI agents.
+
+    from actuent import Actuent
+    client = Actuent()                      # free tier, or Actuent(api_key="ak_...") for Pro
+    results = client.search("barber amsterdam")
+    shoes = client.search("running shoes under €100")["products"]
+    evening = client.plan("Nørreport, Copenhagen", stops=["dinner", "drinks"])
+    fade = client.find_service("skin fade under €30", location="Amsterdam")
+"""
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+__version__ = "0.2.0"
+__all__ = ["Actuent", "ActuentError", "RateLimitError"]
+
+_USER_AGENT = f"actuent-python/{__version__}"
+
+
+class ActuentError(Exception):
+    """An error response from Actuent."""
+
+    def __init__(self, message: str, status: Optional[int] = None, body: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+
+class RateLimitError(ActuentError):
+    """Too many requests. `retry_after` is the number of seconds to wait."""
+
+    def __init__(self, message: str, retry_after: Optional[int] = None, body: Any = None):
+        super().__init__(message, 429, body)
+        self.retry_after = retry_after
+
+
+class Actuent:
+    """Client for the Actuent API (https://docs.actuent.ai).
+
+    api_key: optional Pro key from actuent.ai. Defaults to the ACTUENT_API_KEY environment variable.
+    Without a key you get the free tier (20 requests/minute).
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: str = "https://api.actuent.ai",
+                 agents_url: str = "https://agents.actuent.ai", timeout: float = 60.0):
+        self.api_key = api_key if api_key is not None else os.environ.get("ACTUENT_API_KEY")
+        self.base_url = base_url.rstrip("/")
+        self.agents_url = agents_url.rstrip("/")
+        self.timeout = timeout
+        self.rate_limit: Dict[str, Optional[int]] = {}
+
+    def _request(self, method: str, url: str, body: Optional[Dict[str, Any]] = None) -> Any:
+        headers = {"Accept": "application/json", "User-Agent": _USER_AGENT}
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        request = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                self._remember_limits(response.headers)
+                return json.loads(response.read().decode("utf-8") or "null")
+        except urllib.error.HTTPError as error:
+            self._remember_limits(error.headers)
+            try:
+                payload = json.loads(error.read().decode("utf-8") or "null")
+            except ValueError:
+                payload = None
+            message = (payload or {}).get("error") or (payload or {}).get("message") or f"HTTP {error.code}"
+            if error.code == 429:
+                retry = error.headers.get("Retry-After")
+                raise RateLimitError(message, int(retry) if retry and retry.isdigit() else None, payload) from None
+            raise ActuentError(message, error.code, payload) from None
+
+    def _remember_limits(self, headers: Any) -> None:
+        def number(name: str) -> Optional[int]:
+            value = headers.get(name) if headers else None
+            return int(value) if value and str(value).isdigit() else None
+        self.rate_limit = {"limit": number("X-RateLimit-Limit"), "remaining": number("X-RateLimit-Remaining"),
+                           "reset": number("X-RateLimit-Reset")}
+
+    def search(self, query: str) -> Dict[str, Any]:
+        """Search by topic, domain or page, in any language. Returns {"results": [...LAWP], "products": [...]}.
+
+        Examples: "barber amsterdam", "nike.com", "stripe.com/pricing", "running shoes under €100".
+        """
+        return self._request("GET", f"{self.base_url}/api/search?q={urllib.parse.quote(query)}")
+
+    def get_site(self, domain: str) -> Optional[Dict[str, Any]]:
+        """The LAWP for one site (or None if Actuent can't find it)."""
+        results = self.search(domain).get("results") or []
+        return results[0] if results else None
+
+    def get_page(self, url: str) -> Optional[Dict[str, Any]]:
+        """The LAWP for one page, e.g. "stripe.com/pricing"."""
+        return self.get_site(url)
+
+    def products(self, query: str) -> list:
+        """Products with prices, e.g. "running shoes under €100"."""
+        return self.search(query).get("products") or []
+
+    def check_site(self, domain: str) -> Dict[str, Any]:
+        """Validate a site's /.well-known/lawp.json and its action endpoints."""
+        return self._request("GET", f"{self.agents_url}/api/lawp-check?domain={urllib.parse.quote(domain)}")
+
+    def register(self, site: Dict[str, Any]) -> Dict[str, Any]:
+        """List or update your own site's LAWP (Pro key, verified domain). See docs.actuent.ai/#sdk."""
+        return self._request("POST", f"{self.base_url}/api/register", site)
+
+    def state(self) -> Dict[str, Any]:
+        """Live "State of the AI web" statistics."""
+        return self._request("GET", f"{self.base_url}/api/state")
+
+    # ----- Tools from the Actuent MCP server (the same ones ChatGPT and Claude use) -----
+
+    def _tool(self, name: str, arguments: Dict[str, Any]) -> Any:
+        args = {k: v for k, v in arguments.items() if v is not None}
+        reply = self._request("POST", f"{self.agents_url}/api/mcp",
+                              {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": name, "arguments": args}})
+        if not isinstance(reply, dict) or "result" not in reply:
+            raise ActuentError((reply or {}).get("error", {}).get("message", "Unexpected response"), None, reply)
+        result = reply["result"]
+        text = "".join(part.get("text", "") for part in result.get("content", []) if part.get("type") == "text")
+        try:
+            data = json.loads(text)
+        except ValueError:
+            data = text
+        if result.get("isError"):
+            message = data.get("error") if isinstance(data, dict) else str(data)
+            raise ActuentError(message or f"{name} failed", None, data)
+        return data
+
+    def get_actions(self, domain: str) -> Dict[str, Any]:
+        """A site's actions, whether each is executable, and the JSON Schema of each input."""
+        return self._tool("actuent_get_actions", {"domain": domain})
+
+    def ask_site(self, domain: str, question: str) -> Dict[str, Any]:
+        """Answer a question from one site's own pages, e.g. ("nike.com", "free returns?")."""
+        return self._tool("actuent_ask_site", {"domain": domain, "question": question})
+
+    def nearby(self, query: str, location: str, radius_metres: Optional[int] = None, open_now: Optional[bool] = None,
+               filters: Optional[list] = None) -> Dict[str, Any]:
+        """Places near a location. filters: vegan, vegetarian, gluten_free, wheelchair, outdoor_seating, wifi, kids, dogs."""
+        return self._tool("actuent_nearby", {"query": query, "location": location, "radius_metres": radius_metres,
+                                             "open_now": open_now, "filters": filters})
+
+    def find_service(self, query: str, location: Optional[str] = None, max_price: Optional[float] = None,
+                     currency: Optional[str] = None) -> Dict[str, Any]:
+        """A service or dish with its price at local businesses, e.g. "skin fade under €30"."""
+        return self._tool("actuent_find_service", {"query": query, "location": location, "max_price": max_price, "currency": currency})
+
+    def plan(self, location: str, stops: Optional[list] = None, date: Optional[str] = None, start_time: Optional[str] = None,
+             cuisine: Optional[str] = None, filters: Optional[list] = None) -> Dict[str, Any]:
+        """A timed outing, e.g. stops=["dinner", "drinks"] from 19:00, with places open when you'd arrive."""
+        return self._tool("actuent_plan", {"location": location, "stops": stops, "date": date, "start_time": start_time,
+                                           "cuisine": cuisine, "filters": filters})
+
+    def trip(self, location: str, days: int = 2, start_date: Optional[str] = None, filters: Optional[list] = None) -> Dict[str, Any]:
+        """A 1–4 day city trip: where to stay and a plan for each day."""
+        return self._tool("actuent_trip", {"location": location, "days": days, "start_date": start_date, "filters": filters})
+
+    def events(self, location: Optional[str] = None, query: Optional[str] = None, date_from: Optional[str] = None,
+               date_to: Optional[str] = None) -> Dict[str, Any]:
+        """Upcoming events that websites publish, by city, topic and dates (YYYY-MM-DD)."""
+        return self._tool("actuent_events", {"location": location, "query": query, "from": date_from, "to": date_to})
+
+    def compare_sites(self, domains: list) -> Any:
+        """Compare two or more sites side by side."""
+        return self._tool("actuent_compare", {"domains": domains})
+
+    def compare_products(self, urls: list) -> Dict[str, Any]:
+        """Compare products by URL: price, stock, 90-day price range and cheaper shops."""
+        return self._tool("actuent_compare", {"products": urls})
+
+    def news(self, topic: str) -> Any:
+        """Latest articles on a topic."""
+        return self._tool("actuent_news", {"topic": topic})
+
+    def watch_price(self, url: str, target_price_eur: Optional[float] = None, notify: str = "price",
+                    webhook_url: Optional[str] = None) -> Dict[str, Any]:
+        """(Pro) Get an email, and optionally a webhook, when a product's price drops or it's back in stock
+        (notify="price", "stock" or "both")."""
+        return self._tool("actuent_watch_price", {"url": url, "target_price_eur": target_price_eur, "notify": notify, "webhook_url": webhook_url})
+
+    def price_watches(self) -> Dict[str, Any]:
+        """(Pro) Your price watches."""
+        return self._tool("actuent_watch_price", {"action": "list"})
+
+    def execute_action(self, domain: str, action_id: str, input: Any = None) -> Dict[str, Any]:
+        """(Pro) Perform a site's action. Confirm with your user first."""
+        return self._tool("actuent_execute_action", {"domain": domain, "action_id": action_id, "input": input})
+
+    # ----- Scores and badges -----
+
+    def score(self, domain: str) -> Dict[str, Any]:
+        """A site's agent-readiness score (0–100), label, category and checks."""
+        return self._request("GET", f"{self.base_url}/badge.json?domain={urllib.parse.quote(domain)}")
+
+    def leaderboard(self) -> Dict[str, Any]:
+        """The 100 sites agents found most often this week."""
+        return self._request("GET", f"{self.base_url}/leaderboard")

actuent/langchain.py

@@ -0,0 +1,44 @@
+"""LangChain tools for Actuent.
+
+    from actuent.langchain import get_tools
+    tools = get_tools()              # or get_tools(api_key="ak_...")
+    agent = create_react_agent(llm, tools)
+
+Requires: pip install "actuent[langchain]"
+"""
+
+import json
+from typing import List, Optional, Type
+
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+from . import Actuent
+
+
+class _SearchInput(BaseModel):
+    query: str = Field(description="What to find: a topic ('barber amsterdam'), a domain ('nike.com'), "
+                                   "a page ('stripe.com/pricing') or a product search ('running shoes under €100').")
+
+
+class ActuentSearchTool(BaseTool):
+    """Search the web as structured data with Actuent."""
+
+    name: str = "actuent_search"
+    description: str = (
+        "Search websites and products for the user. Returns each site's pages summarised in plain English, "
+        "the actions a visitor can take (book, contact, buy), and for shopping searches, products with prices. "
+        "Use it instead of browsing raw web pages. Works in any language; results are in English."
+    )
+    args_schema: Type[BaseModel] = _SearchInput
+    client: Actuent = Field(default_factory=Actuent, exclude=True)
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def _run(self, query: str, run_manager=None) -> str:
+        return json.dumps(self.client.search(query), ensure_ascii=False)
+
+
+def get_tools(api_key: Optional[str] = None) -> List[BaseTool]:
+    """Actuent tools for a LangChain agent."""
+    return [ActuentSearchTool(client=Actuent(api_key=api_key))]

actuent/llama_index.py

@@ -0,0 +1,27 @@
+"""LlamaIndex tools for Actuent.
+
+    from actuent.llama_index import get_tools
+    agent = ReActAgent.from_tools(get_tools(), llm=llm)
+
+Requires: pip install "actuent[llamaindex]"
+"""
+
+import json
+from typing import List, Optional
+
+from llama_index.core.tools import FunctionTool
+
+from . import Actuent
+
+
+def get_tools(api_key: Optional[str] = None) -> List[FunctionTool]:
+    """Actuent tools for a LlamaIndex agent."""
+    client = Actuent(api_key=api_key)
+
+    def actuent_search(query: str) -> str:
+        """Search websites and products. Returns each site's pages in plain English, the actions a visitor
+        can take (book, contact, buy), and for shopping searches, products with prices. Accepts a topic,
+        domain, page (domain/path) or product search like 'running shoes under €100'."""
+        return json.dumps(client.search(query), ensure_ascii=False)
+
+    return [FunctionTool.from_defaults(fn=actuent_search)]

actuent-0.2.0.dist-info/METADATA

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: actuent
+Version: 0.2.0
+Summary: Python SDK for Actuent — the search engine for AI agents. Websites and products as structured LAWP, plus LangChain and LlamaIndex tools.
+Author-email: localilabs <support@localilabs.com>
+License: MIT
+Project-URL: Homepage, https://actuent.ai
+Project-URL: Documentation, https://docs.actuent.ai
+Project-URL: Source, https://github.com/localilabs/actuent-python
+Keywords: ai,agents,search,lawp,mcp,langchain,llamaindex
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2; extra == "langchain"
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == "llamaindex"
+Dynamic: license-file
+
+# Actuent for Python
+
+Search the web as structured data. [Actuent](https://actuent.ai) is a search engine for AI agents: it returns websites as **LAWP** (clean JSON with each site's pages and the actions a visitor can take) and products with prices, instead of raw HTML.
+
+```bash
+pip install actuent
+```
+
+```python
+from actuent import Actuent
+
+client = Actuent()                       # free tier; Actuent(api_key="ak_...") for Pro
+site = client.get_site("stripe.com")      # pages + actions for one site
+results = client.search("barber amsterdam")["results"]
+shoes = client.products("running shoes under €100")   # products with prices, in English
+```
+
+Searches work in any language and always come back in English. Free: 20 requests/minute. Pro keys from [actuent.ai](https://actuent.ai): full results and 60/minute. Rate-limit info is in `client.rate_limit`; a `RateLimitError` has `retry_after`.
+
+## LangChain
+
+```bash
+pip install "actuent[langchain]"
+```
+
+```python
+from actuent.langchain import get_tools
+tools = get_tools()          # [ActuentSearchTool]
+```
+
+
+## Plans, services and more (0.2)
+
+```python
+client.plan("Nørreport, Copenhagen", stops=["dinner", "drinks"], start_time="19:00")
+client.trip("Lisbon", days=3)
+client.find_service("skin fade under €30", location="Amsterdam")
+client.nearby("cafe", "Jordaan, Amsterdam", filters=["vegan", "wifi"], open_now=True)
+client.events(location="Copenhagen", query="jazz")
+client.ask_site("nike.com", "free returns?")
+client.compare_products([url_a, url_b])
+client.score("yoursite.com")                     # agent-readiness 0–100
+client.watch_price(url, notify="both")           # Pro: price drops and back in stock
+```
+
+## LlamaIndex
+
+```bash
+pip install "actuent[llamaindex]"
+```
+
+```python
+from actuent.llama_index import get_tools
+tools = get_tools()          # [FunctionTool actuent_search]
+```
+
+## More
+
+- `client.check_site("yoursite.com")`: validate your `/.well-known/lawp.json` and action endpoints
+- `client.register({...})`: list your own site (Pro, verified domain)
+- `client.state()`: live "State of the AI web" numbers
+
+Docs: [docs.actuent.ai](https://docs.actuent.ai) · MCP server for Claude and ChatGPT: `https://agents.actuent.ai/api/mcp`
+
+Made by [localilabs](https://localilabs.com). MIT licensed.

actuent-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+actuent/__init__.py,sha256=Cy7WFUyfmquhytq8Sq1OBUHaavUvDomSfHbIKk_rkRE,10979
+actuent/langchain.py,sha256=YaBuGH4nY_4_dZDYpBMTpnRskCV5yUC8pO8wFioGcao,1611
+actuent/llama_index.py,sha256=nAYN1EQzjPrYfMvN_YQgHc9Wit6jWQ7CODFV9CCRmKA,935
+actuent-0.2.0.dist-info/licenses/LICENSE,sha256=L4f2H9noHi5v96HErbbs_vfIyTCFL3-Bh5j1_ffVE0g,1067
+actuent-0.2.0.dist-info/METADATA,sha256=LrjubqdBioKqZw7y-Y_clOcIkL0CNrmdwu4IRYj83Kg,3202
+actuent-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+actuent-0.2.0.dist-info/top_level.txt,sha256=ATBdStNCgEYObRjMxY6lZKYD01Hbp2W7K5wDU74-1po,8
+actuent-0.2.0.dist-info/RECORD,,

actuent-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

actuent-0.2.0.dist-info/licenses/LICENSE

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

actuent-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+actuent