fastaf-sdk 0.1.0__py3-none-any.whl

fastaf/__init__.py

@@ -0,0 +1,4 @@
+"""Install fastaf-sdk, import fastaf. No optional agent dependencies at import time."""
+from .client import FastAF, FastAFError
+
+__all__ = ["FastAF", "FastAFError"]

fastaf/client.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping
+from urllib.parse import urlsplit
+
+import httpx
+
+Params = Mapping[str, str | int | float | bool | None]
+
+
+class FastAFError(Exception):
+    """HTTP failure, including quota 402; no automatic retry or payment."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        super().__init__(f"FastAF request failed ({response.status_code})")
+        self.status = response.status_code
+        self.body = _decode(response)
+        self.headers = response.headers
+
+
+def _decode(response: httpx.Response) -> Any:
+    content_type = response.headers.get("content-type", "").split(";")[0].strip()
+    if content_type == "application/json" or content_type.endswith("+json"):
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+    if content_type.startswith("image/") or content_type == "application/octet-stream":
+        return response.content
+    return response.text
+
+
+class FastAF:
+    """Synchronous httpx client. Owns its connection pool; use as a context manager.
+
+    Optional transports support mocking/proxies without changing authentication.
+    Redirects are not followed and failed calls are never automatically retried.
+    """
+
+    def __init__(self, api_key: str, *, base_url: str = "https://api.fastaf.co",
+                 timeout: float = 60.0, transport: httpx.BaseTransport | None = None) -> None:
+        if not api_key or re.search(r"\s", api_key):
+            raise ValueError("A nonempty API key is required")
+        url = urlsplit(base_url)
+        if (url.scheme not in {"https", "http"} or not url.hostname or url.username or url.password
+                or url.path not in {"", "/"} or url.query or url.fragment):
+            raise ValueError("base_url must be an HTTP(S) origin without credentials, path, query or fragment")
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        self._http = httpx.Client(base_url=base_url, headers={"Authorization": f"Bearer {api_key}"},
+                                  timeout=timeout, transport=transport, follow_redirects=False)
+
+    def request(self, endpoint: str, params: Params | None = None, *, method: str = "GET") -> Any:
+        if not re.fullmatch(r"[a-z][a-z0-9_-]*", endpoint):
+            raise ValueError("endpoint must be a single endpoint name, not a URL or path")
+        if method not in {"GET", "POST"}:
+            raise ValueError("Use GET or POST")
+        values = {key: value for key, value in (params or {}).items() if value is not None}
+        kwargs = {"params": values} if method == "GET" else {"json": values}
+        response = self._http.request(method, f"/v1/{endpoint}", **kwargs)
+        if not response.is_success:
+            raise FastAFError(response)
+        return _decode(response)
+
+    def search(self, query: str, **params: str | int | float | bool | None) -> Any:
+        return self.request("serp", {**params, "query": query})
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> FastAF:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()

fastaf/tools.py

@@ -0,0 +1,39 @@
+"""Optional framework factories. Credentials live in closures, never tool schemas."""
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:
+    from .client import FastAF
+
+DESCRIPTION = "Search the public web with FastAF for source links and snippets. Each call spends API credits."
+
+
+def _search(client: FastAF) -> Callable:
+    def fastaf_search(query: str, results: int = 5) -> str:
+        """Search the public web. query: nonempty search text; results: 1-10."""
+        if not query.strip() or len(query) > 2000:
+            raise ValueError("query must contain 1-2000 characters")
+        if isinstance(results, bool) or not isinstance(results, int) or not 1 <= results <= 10:
+            raise ValueError("results must be an integer from 1 to 10")
+        return json.dumps(client.search(query, results=results), ensure_ascii=False)
+    return fastaf_search
+
+
+def langchain_tool(client: FastAF):
+    """Requires fastaf-sdk[langchain]."""
+    from langchain_core.tools import StructuredTool
+    return StructuredTool.from_function(_search(client), name="fastaf_search", description=DESCRIPTION)
+
+
+def llamaindex_tool(client: FastAF):
+    """Requires fastaf-sdk[llamaindex]."""
+    from llama_index.core.tools import FunctionTool
+    return FunctionTool.from_defaults(fn=_search(client), name="fastaf_search", description=DESCRIPTION)
+
+
+def crewai_tool(client: FastAF):
+    """Requires fastaf-sdk[crewai]."""
+    from crewai.tools import tool
+    return tool("fastaf_search")(_search(client))

fastaf_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.5
+Name: fastaf-sdk
+Version: 0.1.0
+Summary: FastAF API client and optional agent tools
+Project-URL: Homepage, https://fastaf.co
+Project-URL: Repository, https://github.com/fastaf-co/fastaf-sdk
+Author-email: FastAF <dev@fastaf.co>
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: crewai
+Requires-Dist: crewai<2,>=1; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=1; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core<0.15,>=0.14; extra == 'llamaindex'
+Provides-Extra: test
+Requires-Dist: build<2,>=1; extra == 'test'
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# fastaf-sdk
+
+[FastAF](https://fastaf.co) · Docs: https://fastaf.co/docs/
+
+
+Distribution name: **fastaf-sdk**. Import: **fastaf**. The unrelated `fastaf`
+PyPI distribution is not this SDK. Nothing here has been published.
+
+Python 3.10+. Local installation (from this directory):
+
+```sh
+pip install -e .
+# Install only integrations you use:
+pip install -e '.[langchain,llamaindex,crewai]'
+```
+
+```python
+import os
+from fastaf import FastAF, FastAFError
+
+with FastAF(os.environ["FASTAF_API_KEY"]) as client:
+    data = client.search("best espresso machine", results=5)
+    markdown = client.request("scrape", {"url": "https://example.com", "formats": "markdown"})
+    data = client.request("serp", {"query": "coffee"}, method="POST")
+```
+
+`request(endpoint, params)` covers the live `/v1/*` endpoints. Returns decoded
+JSON, text, or bytes for images. Keys stay in Authorization headers. Errors
+raise `FastAFError` with `status`, `body`, and `headers` (including Retry-After).
+Network/timeout exceptions remain httpx exceptions. Default timeout: 60 seconds;
+override `timeout=30`. There are no automatic retries, redirects or x402 payments.
+A 402 on keyed REST means insufficient credits, not permission to spend a wallet.
+Close the client or use its context manager. Do not put keys in browser code.
+
+## Agent tools
+
+```python
+from fastaf.tools import langchain_tool, llamaindex_tool, crewai_tool
+
+# Use inside the client's lifetime. Each accepts the same FastAF client.
+search = langchain_tool(client)    # StructuredTool
+search = llamaindex_tool(client)   # FunctionTool
+search = crewai_tool(client)       # CrewAI tool
+```
+
+Tools accept `query` and `results` (1-10, default 5). They return JSON strings;
+credentials are not part of agent-visible schemas. Each call consumes API
+credits, so configure agent step limits. Integrations import lazily.
+
+## Tests and local packaging
+
+```sh
+pip install -e '.[test,langchain,llamaindex,crewai]'
+pytest
+python -m build
+```
+
+Tests use httpx.MockTransport, never real keys or billable calls. Without optional
+frameworks, their integration tests skip; install all extras to run the full suite.
+The private distribution classifier deliberately blocks uploading to PyPI.

fastaf_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+fastaf/__init__.py,sha256=is0E-dGY60EK5YuVMAtlX1IZvOC0rrxE84UUiTEDy3w,165
+fastaf/client.py,sha256=GkRMQ9UpbeoV7VlE09OJzQRgpsARHNrinRnn2PqcP_M,3190
+fastaf/tools.py,sha256=8nTyuUkrOLiwjgbU5TBlPELzL412ffVAkubm1iRvzkw,1554
+fastaf_sdk-0.1.0.dist-info/METADATA,sha256=w0Nl63o_8-tF2kuJzfWGK6PILgllzdx8rZB1_LQKTzg,2912
+fastaf_sdk-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fastaf_sdk-0.1.0.dist-info/RECORD,,

fastaf_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any