fastaf-sdk 0.1.0__tar.gz

fastaf_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,60 @@
+# 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/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastaf-sdk"
+version = "0.1.0"
+description = "FastAF API client and optional agent tools"
+authors = [{name = "FastAF", email = "dev@fastaf.co"}]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=1,<2"]
+llamaindex = ["llama-index-core>=0.14,<0.15"]
+crewai = ["crewai>=1,<2"]
+test = ["pytest>=8,<10", "build>=1,<2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastaf"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://fastaf.co"
+Repository = "https://github.com/fastaf-co/fastaf-sdk"

fastaf_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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/tests/conftest.py

@@ -0,0 +1,5 @@
+"""Prevent optional frameworks from sending test telemetry."""
+import os
+os.environ["OTEL_SDK_DISABLED"] = "true"
+os.environ["CREWAI_TRACING_ENABLED"] = "false"
+os.environ["GRADIO_ANALYTICS_ENABLED"] = "False"

fastaf_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,78 @@
+import json
+
+import httpx
+import pytest
+
+from fastaf import FastAF, FastAFError
+
+KEY = "test-key-not-a-secret"
+
+
+def test_get_encoding_and_auth():
+    def handler(request):
+        assert request.url.path == "/v1/serp"
+        assert request.url.params["query"] == "coffee & tè"
+        assert request.url.params["html"] == "false"
+        assert "omit" not in request.url.params
+        assert request.headers["Authorization"] == f"Bearer {KEY}"
+        assert request.extensions["timeout"]["read"] == 60
+        return httpx.Response(200, json={"ok": True})
+    with FastAF(KEY, transport=httpx.MockTransport(handler)) as client:
+        assert client.search("coffee & tè", html=False, omit=None) == {"ok": True}
+    assert client._http.is_closed
+
+
+def test_post_text():
+    def handler(request):
+        assert request.method == "POST"
+        assert not request.url.query
+        assert json.loads(request.content) == {"url": "https://example.com", "dynamic": True}
+        return httpx.Response(200, text="# Title", headers={"Content-Type": "text/markdown"})
+    with FastAF(KEY, transport=httpx.MockTransport(handler)) as client:
+        assert client.request("scrape", {"url": "https://example.com", "dynamic": True}, method="POST") == "# Title"
+
+
+def test_binary():
+    with FastAF(KEY, transport=httpx.MockTransport(lambda _: httpx.Response(200, content=b"png", headers={"Content-Type": "image/png"}))) as client:
+        assert client.request("screenshot") == b"png"
+
+
+@pytest.mark.parametrize("status", [302, 401, 402, 429, 503])
+def test_errors_and_no_retry_or_redirect(status):
+    calls = []
+    def handler(request):
+        calls.append(request)
+        return httpx.Response(status, json={"error": "test"}, headers={"Retry-After": "3", "Location": "https://evil.test"})
+    with FastAF(KEY, transport=httpx.MockTransport(handler)) as client:
+        with pytest.raises(FastAFError) as error:
+            client.search("coffee")
+        assert error.value.status == status
+        assert error.value.body == {"error": "test"}
+        assert error.value.headers["Retry-After"] == "3"
+        assert KEY not in str(error.value)
+    assert len(calls) == 1
+
+
+@pytest.mark.parametrize("endpoint", ["../usage", "/serp", "https://evil.test", "serp?x=y", "serp#x"])
+def test_endpoint_injection(endpoint):
+    with FastAF(KEY, transport=httpx.MockTransport(lambda _: pytest.fail("must not fetch"))) as client:
+        with pytest.raises(ValueError):
+            client.request(endpoint)
+
+
+@pytest.mark.parametrize("base", ["https://user:pass@example.com", "https://example.com/path", "https://example.com?key=x", "file:///tmp"])
+def test_origin_injection(base):
+    with pytest.raises(ValueError):
+        FastAF(KEY, base_url=base)
+
+
+def test_timeout_and_invalid_json():
+    def timeout(request):
+        raise httpx.ReadTimeout("mock timeout", request=request)
+    with FastAF(KEY, transport=httpx.MockTransport(timeout)) as client:
+        with pytest.raises(httpx.ReadTimeout):
+            client.search("coffee")
+    with FastAF(KEY, transport=httpx.MockTransport(lambda _: httpx.Response(502, text="not-json", headers={"Content-Type": "application/json"}))) as client:
+        with pytest.raises(FastAFError) as error:
+            client.search("coffee")
+        assert error.value.body == "not-json"

fastaf_sdk-0.1.0/tests/test_tools.py

@@ -0,0 +1,48 @@
+import json
+import httpx
+import pytest
+from fastaf import FastAF
+from fastaf.tools import _search, langchain_tool, llamaindex_tool, crewai_tool
+
+
+@pytest.fixture
+def client():
+    def handler(request):
+        assert request.url.path == "/v1/serp"
+        assert request.url.params["query"] == "coffee"
+        assert request.url.params["results"] == "5"
+        return httpx.Response(200, json={"organic_results": []})
+    with FastAF("test-key", transport=httpx.MockTransport(handler)) as client:
+        yield client
+
+
+def test_search_validation(client):
+    search = _search(client)
+    for query, results in [("", 5), ("coffee", 0), ("coffee", 11), ("coffee", True)]:
+        with pytest.raises(ValueError):
+            search(query, results)
+    assert json.loads(search("coffee")) == {"organic_results": []}
+
+
+def test_langchain(client):
+    pytest.importorskip("langchain_core")
+    tool = langchain_tool(client)
+    assert tool.name == "fastaf_search"
+    assert json.loads(tool.invoke({"query": "coffee"})) == {"organic_results": []}
+    assert "api_key" not in tool.args
+
+
+def test_llamaindex(client):
+    pytest.importorskip("llama_index.core")
+    tool = llamaindex_tool(client)
+    assert tool.metadata.name == "fastaf_search"
+    assert json.loads(tool.call(query="coffee").content) == {"organic_results": []}
+    assert "api_key" not in tool.metadata.get_parameters_dict()["properties"]
+
+
+def test_crewai(client):
+    pytest.importorskip("crewai")
+    tool = crewai_tool(client)
+    assert tool.name == "fastaf_search"
+    assert json.loads(tool.run(query="coffee")) == {"organic_results": []}
+    assert "api_key" not in tool.args_schema.model_json_schema()["properties"]